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Letter from the Series Editor 


Game development has reached a fever pitch in the past couple of years— photorealistic 
rendering, advanced physics modeling, a million-plus polygon worlds—and 
multiprocessor consoles and PCs are powering the revolution. At the same time, 
experimentation with scripting languages to help control the high-level aspects of games 
has gone from a convenience to an absolute necessity. No longer can game 
programmers think of something as absurd as writing a game in C/C++. Game engines 
may be written in C/C++, but games—no longer. Today's state-of-the-art games are 
controlled almost exclusively with scripting languages. 

In the past, scripting languages were custom-made or derivative works made up of the 
C/C++ compiler and Creative use of the pre-processor. Times have changed, and today 
developers are faced with a number of potential scripting languages to use in their 
games. Notable players are Python, Lua, and Ruby. Each of these languages has 
advantages and disadvantages, but any of them can do the job. Game Programming with 
Python, Lua, and Ruby takes you on a tour and tutorial of each language, highlighting 
its strengths and weaknesses and offering you detailed examples of getting each 
language up and running and interfaced to your game and host languages, such as 
C/C++. 

With Game Programming with Python, Lua, and Ruby, you won't spend a lot of time 
leaming irrelevant material—instead, you'll get just the information you need. Tom 
Gutschmidt delivers a non-biased view of each language and gets you up and running as 
soon as possible in each of the most popular scripting languages today—Python, Lua, 
and Ruby. 


Sincerely, 



Andre LaMothe 


Series Editor 
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Introduction 


This book is unusual because it covers game programming in three different seripting 
languages in three separate seetions. Python, Lua, and Ruby are wonderful languages 
used all over the world to build efficient, flexible, scalable, and well-integrated 
programs and Systems. 

For the same reasons that these languages have been great choices for other projects, 
Python, Lua, and Ruby also are great for making games. This discovery, in fact, was 
made over a decade ago. Chances are youVe played a computer game that utilized one 
of these languages during development. You may be currently working through game 
levels that were designed with Lua, or playing on a graphics engine prototyped in 
Python, or using an Internet ladder developed with Ruby. 
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Why Learn Another Language? 

Programming languages require a lot of diseipline to learn. They eaeh have their own 
set of formal speeifieations. They all have unique ways of handling data, data struetures, 
referenee meehanisms, and eommand flow. And undemeath all this they eaeh have their 
own design philosophy. So the question arises: "Why would anyone want to learn a new 
programming language, let alone three new programming languages?" 

Well, first of all, these three high-level languages are great starting plaees to learn 
programming. For the most part, they are eleanly designed, well doeumented, and very 
kind to new programmers. Despite this, they are not toys. They are flexible and 
powerful, suited for both large projeets and elassroom exereises. 

Seeond, every language has its own strength and weaknesses. The deeisions you must 
make during Software and game development beeome easier when more than one 
possible tool is available to you. In an ideal development environment, problems are 
solved in a general way and then the best language for a partieular job is ehosen. It may 
be diffieult in tomorrow's job market for a programmer to get away with knowing only 
one or two languages well. 

Finally, these three languages are really very similar. Mueh of what you learn firom one 
will be applieable to the others. The more languages you learn, the easier the next one 
will be to piek up. This eompound learning eurve eventually begins to work greatly to 
your advantage, and after enough experienee you will get to the point where you can 
leam a new language in days, simply by relating what is in a given manual to what you 
already know. 
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Whafs on the CD-ROM? 


The CD that comes with this book is designed to launch automatically when inserted 
into a machine running the Windows operating system. On the CD is the source code 
for all of the samples and programs written in the book. These are separated into folders 
organized by chapter. 

The CD also contains the Software necessary to install Python, Ruby, or Lua on your 
System. This Software is also separated into different folders—a Python folder, a Ruby 
folder, and a Lua folder. 

Also on the CD are several open-source libraries and Utilities that are either used for the 
source code samples or as examples in this book. These includes PythonWin, Distutils, 
Numeric Python, PAWS, Py2Exe, Pygame, PyOpenGL, Pyzzle, RubySDL, LuaSDL, 
and Clanruby. 
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Part ONE: Introducing High-Level Languages 


Welcome to the first part of this book! In this part, TU be introducing high-level 
languages and covering some of their parallel features. fll introduce Python, Lua, and 
Ruby, but Pll save the gory details for the later parts of the book. Part One is a gentle 
introduetion to these languages' features, syntax, and similarities, as well as to their 
cohorts and partners in the gaming industry. 7 
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Chapter 1. High-Level Language OverView 

AU programmers are playwrights, and all computers are lousy aetors. 

-Unknown, quoted by Miehael Moneur in The Quotations Page 

Where to start? There is mueh to cover, and we have a very short time together. This is 
Chapter 1 of Game Programming with Python, Lua, and Ruby. In this ehapter TU 
diseuss the speeifie pros and eons of programming with these high-level seripting 
languages (after explaining what a high-level seripting language is, of eourse), delve 
into their properties and history, and then wrap up the ehapter with a listing of some of 
the major projeets these languages are responsible for. 
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High-Level Language Roots 

In the beginning, a programmer needed to know everything about the intemal workings 
of a specific computer in order to program it. This took quite a bit of knowledge and 
effort. Then, from within the programming industry, an idea emerged. The idea was to 
reduee the amount of knowledge of the internal workings of the eomputer a programmer 
needed to write programs (some eall this idea eneapsulation). If adopted, this eoneept 
eould make it easier and faster to program, and the program itself eould be less error 
prone. A seeond idea followed this first one: If programs eould be presented in a 
familiar language, then programmers eould learn them quiekly. These ideas eventually 
led to high-level languages. 

High-level languages were created to make programming easier, but today's high-level 
programming languages have seriously evolved from early predeeessors like 
FORTRAN in the 1950s. You have your high-level languages, your high-level scripting 
languages, your high-level open-source seripting languages, your high-level open 
souree objeet-oriented seripting languages, and your very high-level open-source objeet- 
oriented seripting languages (yes, the dreaded VHLOSOOSLs). So mueh for easier. 
Despite the long, often buzzword-filled names, there are those of us who love these 
languages. And luckily we like to spend time explaining why. 

Before you eommit to a projeet with a eertain language, spend some time under the 
hood, read a book or two, and eheek into the language's eommunity. Most good 
languages will already have a large and very aetive user base—that is, if they have 
useful features that appeal to a wide audienee and if they are capable of getting the job 
done. This ehapter and the next spend a bit of time showing how Python, Lua, and Ruby 
appeal to a wide range of jobs and professionals and how their communities have grown 
in power and presenee in reeent years. 

NOTE 

Open Souree Software 

The basic definition of open souree Software is Software that has its eode base opened 
up and viewable to users. Anyone can look under the hood of open souree Software to 
see how it works. 

Open souree Software likely originated with the United States government. In the 1960 
and 70s, the U.S.was funding Systems of distributed eomputers that would later beeome 
the Internet, and they actively eneouraged scientists to develop teehnologies that eould 
facilitate distributed eomputing. Aeademie researehers, ineluding those at MIT, UCLA, 
Berkeley, and Stanford, and later eorporate researehers at eompanies like IBM and 
Xerox began developing teehnologies for eomputers and operating Systems to 
eommunieate with eaeh other. Out of this movement eame Utilities such as Sendmail 
and TCP/IP. Other tools, like Emaes, Perl, and Einux, followed. 

Open souree does not neeessarily mean "firee." Open souree eode is usually free to 
download, view, and modify, but most open souree Software is eopyrighted and 
possesses some sort of lieense. Often there are restrictions on its use. Eor instanee, many 
open souree lieenses require that if modifieations are made to souree eode, the 
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modifications need to be released to the public at large. This means that open souree 
utilization in private, eommereial Software development involves other eosts. Of eourse, 
using eommereial Software also involves Software licenses and tracking copies and 
usage. 
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How Programming Languages Work 

Let's ignore Webster and Oxford and pretend that the word language simply refers to a 
System used to eommunieate. Languages possess syntax, and syntax defines the order, 
arrangement, or strueture of the System of eommunieation. 

This book is written in English, a language sometimes referred to as Ameriean or 
Present-Day English, whieh evolved firom the Early Modern, Middle, and Old English 
languages. Some historians and linguists elaim that forms of English ean be traeed 
through Gothie, Eatin, and Greek, eventually finding roots in Sanskrit (see Eigure 1.1). 

Figure 1.1. A comparison between English and computer language roots 
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If you traee programming languages baek to their souree, you'll find that all eomputers, 
or at least their CPUs, have an intemal maehine language that they exeeute direetly. 
Internally, all data in a modern digital eomputer is stored as binary on and off States. 

The tools used to manipulate these on/off States are eoded in a binary representation and 
normally eonsist of operation eodes and addresses. The operation eode indieates whieh 
operation is to be earried out, while the address dietates the memory loeation. The 
operation basieally amounts to what, and the address basieally amounts to where. This 
proeess looks something like Table 1.1. Given the operation eodes and address in Table 
1.1, a programmer ean enter in the instruetions in pure binary form as: 

00100010 10010101 


Table 1.1. Sample Maehine Language Instruetions 


Procedure 

Operation 
Address Eoeation 


Binary 

00100010 

10010101 


English Translation 

means "load(X)" 

means "loeation 13" on the CPU 
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These instructions would load X into location 13. As you can imagine, it is very tedious 
to write this way. A programmer needs to be especially careful to keep track of which 
address locations he is using to store data; program errors often lead to operations 
overwriting the wrong addresses. 

Programming languages express these operations and addresses at a higher level of 
logic than the low-level CPU code. They are translation systems that allow a computer 
and a person to communicate with each other in a medium that is something between 
English and CPU binary. With a programming language, a person can program what 
actions a computer will take and the types of data the program acts upon without having 
to speak the computer's language. 


CPU is an abbreviation for Central processing unit. Often referred to as the 
processor or Central processor, the CPU performs most of a computefs 
calculations. CPUs are normally one or more printed Circuit boards, but may be 
housed in a single chip called a microprocessor. CPUs typically consist of an 
Arithmetic Logic Unit (ALU) that performs logical operations and a Control 
Unit that extracts instructions firom memory and decodes and executes them. 
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Low-Level Languages 


Each CPU has its own unique machine language, which consists of binary numbers 
only. Machine languages are tedious and repetitive, two things that humans are poor at 
and seem to dislike universally. These maehine languages are low-level languages. 
Low-level languages elosely refleet the inner workings of a eomputer and are 
sometimes referred to as maehine-oriented languages. 

The most prominent example of a low-level language is assembly. Assembly language 
is one step higher than maehine language and eonsists of numerie instructions for a 
speeific eomputer arehiteeture. Assembly is limited beeause it needs detailed 
instructions, and there isn't much portability from platform to platform. 

In assembly, machine language commands are replaeed by mnemonic eommands on a 
one-to-one basis. An assembler program then takes eare of eonverting the mnemonie 
into eorresponding maehine language binary. In assembly, a programmer ean also use 
symbolie addresses for data items. The assembler program will assign these symbolie 
addresses to machine addresses and make sure they do not overlap or overwrite eaeh 
other. Today, most assembly programming is reserved for high-end performanee deviee 
drivers, where exeeution speed and eode size are more important than rising 
development eosts. 

In the early days of games, assembly was the mainstay, and eommon game platforms 
were MS-DOS, Apple, and the Atari 800. But as game programs grew in size, 
programmers found that assembly was pretty poor at sealing, and as eode grew 
programs beeame exponentially more diffieult to maintain, and testing and debugging 
them beeame more and more diffieult. 

After assembly languages eame eompiled languages like C, COBOL, and FORTRAN. 
With a eompiled language, the programmer writes source eode, and then a eompiler 
takes the souree eode and translates it into maehine language for a partieular eomputer. 
With a eompiler hard at work, the programmer ean ignore some of the maehine- 
dependent details, and with a good eompiler the program will run almost as fast as with 
assembly. 

C in partieular really made large-seale programming possible by automating mueh of 
what programmers found diffieult in assembly. C also universalized the idea of 
functions, so for the first time programmers could share functions they wrote with eaeh 
other. This led to larger development teams and a growing pool of development tools. 
Great games eame out of C (and stili do), like Doom and X-Wing. 
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Today's High-Level Languages 

The terms high-level, interpreted, and scripting all share a similar conceptual space 
when it comes to programming, and this often causes confusion. Over the next few 
pages ril explain each term. Pay attention—there may be a quiz coming up! 

High-level languages are designed with the native language of the programmer in mind. 
They are sometimes referred to as problem-oriented languages and are often very 
specific in focus. BASIC is a good example of a high-level language; it was designed 
for first-time programmers as a leaming tool. COBOL and FORTRAN are other good 
examples. COBOL was designed for business problems, and FORTRAN for solving 
scientific and mathematical problems. 

NOTE 

Python is sometimes referred to as a "Very High Level Language" (VHLL). This term 
appeared in the mid 1990s to describe languages used for rapid prototyping. Two 
features that supposedly separate VHLLs firom your Standard high-level language are 
dynamic types and an interactive environment that allows you to make changes without 
having to go through the entire relink recompile steps. 

Instructions in high-level languages closely resemble everyday language, making high- 
level languages much easier to leam and use than their low-level equivalents. The 
programmer does not need to have detailed knowledge of the internal working of the 
computer in order to program instmctions. Each instmction in high-level is equivalent 
to several machine code instmctions that then are either compiled or interpreted to 
translate them into machine code. 

Interpreted versus Compiled Languages 

A high-level interpreted language translates the programmer's written code step-by-step 
at mntime, or when the program is actually mnning. A high-level compiled language 
translates a programmer's written code before the program is mn, a process normally 
called compiling. This changes the written code into an executable or object-code that 
can then be mn as a program on a computer. 

Many modern programming languages allow themselves to be both interpreted and 
compiled, but normally a particular language is more suited to one or the other. AWK, 
Perl, and Python are examples of interpreted programming languages. BASIC, COBOE, 
C, and EORTRAN are examples of compiled programming languages. 

When a program is compiled, the compiler takes the source code files and generates 
object code with those fides. The object code is then wrapped together during a linking 
process to produce an actual executable. This process is illustrated in Eigure 1.2. 

Figure 1.2. The process of compiling source code into an executabie fiie or 

program 
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When comparing the two types of languages, you can usually make two generalizations. 
The first is that interpreted programs are usually mueh slower than their eompiled 
eounterparts (although the aetual proeess of eompiling may take quite a bit of time as 
well). The seeond is that interpreted languages are more flexible at runtime than 
eompiled languages beeause they ean interaet with the exeeution environment. In other 
words, in order to gain flexibility, you must slow down. 

Scripting Languages 

Seripting is a term used to denote the seripting of a computer, akin to an actor who 
follows a script to perform a play. A scripting language is a high-level language used to 
assemble components into a predefmed Software architecture. Scripting languages, 
sometimes called glue-languages, are designed for scripting the operation of a 
computer. Normal operations that would be considered scripting are administrative 
tasks such as running automatic backups, text processing, running server-side requests 
such as CGI processing, or automating Software tests. Python, Lua, and Ruby are 
considered scripting languages in one form or another, as are ASP, AWK, JavaScript, 
Perl, and VB Script. 

The scripting-language family is hard to pin down. VHLL languages include the various 
types of UNIX shell command-line interpreters, and even languages like AWK, Perl, 
and Lisp can be classified as scripting languages. Unfortunately, there is no universally 
accepted defmition of what a pure scripting language actually is, but they usually have 
most of the following features: 

• They are interpreted languages. 

• They possess a simple syntax. 

• Variables are dynamic, so that they can act as strings or numbers, depending on 
what operation is being performed on them. 
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• Variables are created when referenced, as opposed to being allocated to memory 
early on or during compile time. Internal details about the variables are only 
resolved when neeessary. This proeess is sometimes ealled late binding. 

• They possess high-level string manipulation features. Coneatenation and 
searehing are built into the language. 

• They do not possess pointers. 

• The programmer does not handle memory alloeation; the language handles it 
automatieally. 

• Garbage eolleetion (release of unused memory) is handled automatieally. 

• The language is interaetive and can give feedbaek while running, often pointing 
out errors, mistakes, and problems. 

• The eode is stored in a plain text format. 

• Proeessor and operating system independenee exists, and the eode ean work in 
many different environments. 

• They simplify the usage of eommon eommands such as array sizes, data types, 
or expressions. Common eommands are often built in. 

NOTE 

Statieally versus Dynamieally Typed Languages 

The speeific system by whieh data is organized in a program is ealled the type 
System. There is an actual diseipline devoted to the design and study of type 
Systems, ealled type theory. In praetiee, however, there are normally only two 
type Systems: static and dynamie. 

Statieally typed languages need predefmed types for pieees of data, and values 
ean only have one fixed typed. Statie Systems are sometimes ealled type-safe or 
strongly typed. C++ and Java are examples of statieally typed Systems. 

Dynamie Systems treat data loeations interehangeably. They are sometimes 
ealled latently typed Systems. Again, the key here is flexibility versus speed. 
Dynamie Systems are a bit slower during runtime than their statie brethren, but 
they are faster to eode, as there is no need to predefine variables or check for 
buffer overflow against them. Examples of dynamieally typed Systems include 
Eisp, JavaScript, TCE, and Prolog. 

• Statements are usually terminated by returns or new lines, rather than with 
semicolons or punctuation. 

• They are optimized for programmer efficiency as opposed to program 
efficiency. 

• They are optimized for text manipulation, data filtering, system applications, 
and/or building graphical user interfaces. 

• Components of foreign eode, such as shell eommands, other language libraries, 
or COM, can be embedded or "glued" to the Scripts, and the language provides 
interfaces to external components. This proeess is ealled extensibility. 

• They are considered a rapid prototyping language. 
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The Pros of High-Level Languages 

The cost of Software is determined by the time it takes to test, debug, modify, and 
maintain a eode base. In a not-too distant past, the programming field was a mueh more 
statie one. Programming was done in a eontrolled hardware environment, and things 
like testability, modifieation, and portabibty weren't as important. 

High-level languages exist because human time is important. Often the loss of eomputer 
runtime effieiency will gladly be traded for aetual savings in human labor. The eode 
base for a projeet using a high-level language might be three times shorter than Java and 
fi ve times shorter than C++. 

Probably the biggest problem with low-level eode is that adapting it to different 
architectures (platforms) ean be problematic. If you cut C off from its Standard 
eompilers and libraries, it is pretty mueh incapable of porting to a different arehiteeture. 
Generally, low-level eode has to be rewritten for eaeh speeifie platform. 

High-level languages, on the other hand, are very portable, only needing an alteration to 
the interpreter or eompiler for the new platform—or needing nothing at all. Compilation 
time is usually short—measured in seeonds sometimes. Human-time debugging on a 
new platform, espeeially in a low-level language like assembly, ean easily take weeks. 
This is an obvious trade off 

Another big benefit of high-level languages is reusability. High-level eode ean be 
erafted into small components that are easy to use, as well as easy to organize and bring 
into future projeets. Such modularity promotes the ereation of formal and informal eode 
libraries. Most high-level languages have partieularly great libraries for putting together 
graphieal user interfaees. 

Higher-level languages have more human readable words and phrases and fewer 
abstract symbols, peeuliar syntax, and abbreviations. This ean make them easier to write 
and maintain. This makes testing, debugging, and modifying an easier task. Most 
importantly, it makes reading them easier, a boon for the high turnover world of 
Software development. 

Safety in souree eode is a big issue these days. Many high-level language features have 
the interesting side effect of produeing more secure, bug-free eode. 

Take, for instance, buffer overruns. A buffer is a device or structure that holds data. 
Buffer overruns occur when someone overflows a buffer by giving it more data than it 
ean handle. A simple example is a login prompt to a computer or Website. The 
programmer who develops the login expects that most login names will not be more 
than eight characters long and gives the buffer that holds the login data enough space in 
memory to hold eight characters. But then some malicious user comes along and writes 
257 characters to the login. If the buffer and input login haven't been specifically 
designed to handle such a case, the Software will fail. Worse, it could allow the user the 
ability to write data somewhere besides the login prompt. 

CERT (the Computer Emergency Response Team) reports that a majority of bugs and 
exploitable holes in Software (majority meaning as high as 80 percent) are caused by 
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simple buffer overruns. This type of exploit is very eommon beeause manually eoding 
pointers and garbage eolleetors ean be a very buggy and error-prone enterprise. High- 
level languages normally take eare of these tasks automatically for the programmer. 
Taking away the manual proeess of handling pointers, automatieally handling garbage 
eolleetion, and assigning memory alloeation of variables at runtime makes it diffieult to 
eause buffer overruns. 

My favori te feature of high-level languages is that they are easy to learn—so easy, in 
fact, that they are often eonsidered fun. High-level languages are partieularly suited for 
applieations in whieh: 

• The main foeus is to eonneet existing eomponents. 

• A GUI is required. 

• A lot of string manipulation is required. 

• You expeet the applieation's funetions to evolve rapidly or ehange quiekly over 
time. 
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Cons of High-Level Languages 

How high-level can a language get, and what are the potential problems associated with 
them? In Star Trek, science-fiction computers communicate with their commanders in 
an almost human language. Our Science fiction telis us that the higher-level a language 
is, the easier it is to communicate, the better. In real life this isn't the case. 

The biggest problem with high-level languages is that they are slower than their low- 
level counterparts. There is a give-and-take relationship between the speed of 
development and the efficiency of a program. C is speed efficient because the 
programmer handles all of the low-level resource management by hand. 

Since they aren't as speedy and they handle low-level resource management themselves, 
high-level languages are not great for engineering system-level programs like device 
drivers or kernels, or other situations in which you need tight control over low-level 
tasks, like memory allocation. Lack of speed also makes them poorly suited to 
computationally intensive applications, like those that build data structures and 
algorithms firom scratch. In particular, a low-level language may be more suited to your 
application if: 

• It needs to implement complex algorithms or data structures. 

• It needs to manipulate large data sets. 

• Execution speed is critical. 

• The functions are well defined and will not change. 

The pros and cons of high-level languages are highlighted in Table 1.2. 


Table 1.2. High-Level Language Pros and Cons 


Pro 

Saves human time 
Portable to many platforms 

Modularity and reusability 

Easier to read, write, and maintain 

Auto-management of many bug-prone 
features 

Easy to leam 


Con 

Eess efficient during computer mntime 

Specific platforms aren't as efficiently 
utilized 

Can lead to dizzyingly high number of 
libraries 

Eoss of some control over code organization 
Eess low-level control of resources 

Too many programmers could lower one's 
salary! 


NOTE 

High-level languages are criticized more often for their lack of speed than anything else. 
But keep in mind that they usually can be compiled or semi-compiled. This can make 
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them much faster than languages like Perl, AWK, or other rivals. Also, today's 
machines are 500-2000 times faster than their predecessors from the 1980s. 


26 



A Brief History of Structured Programming 


In thel960s Software development went through a number of growing pains. 
Development schedules often ran far behind predictions, costs were much higher than 
projected, and often the end Software produet was unreliable or buggy. People began to 
realize that Software development was extremely diffieult, and some folks began to 
research development methods of this new field to see what eould be improved. Out of 
this researeh eame the eoneept of struetured programming. 

Struetured programming is a method of programming designed to help make large 
programs easier to read and is a predeeessor to Objeet-Oriented Programming. 
Structured programs are usually illustrated in simple graphs that have a top-down 
approach and flow. Figure 1.3 illustrates a structured-programming graph in which the 
circles represent starting and ending points, the squares represent program blocks, and 
the diamonds represent branches. 

Figure 1.3. An illustration of a simple structured ianguage 



NOTE 

Object-Oriented Programming 

Object-Oriented Programming (or OOP) is actually a design methodology that de fines 
programs in terms of objects. Objects are entities that combine both state (data) and 
behavior (methods). In pure OOP, programs are sets of objects that communicate with 
each other to do various tasks. This is a pretty different design than procedural 
languages (the Standard before OOP), where data and procedures are separated. 

Unfortunately, there is some disagreement about exactly what features are required to 
qualify a programming Ianguage as "object-oriented," so giving a definitive description 
of an OOP Ianguage is diffieult. Traditionally, the first OOP Ianguage is considered to 
be Simula 67, whose OOP features were later refined with Smalltalk. OOP really took 
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off in the mid 1980s with C++—some argue because it was well suited to make GUIs, 
which were booming in popularity. OOP features were then added to several languages, 
such as Perl, Ada, BASIC, Lisp, and Pascal, and several new languages that embraced 
the OOP methodology were developed, like Java and Eiffel. 

The main idea behind structured programming is to divide and conquer. As computers, 
technology, and Software have advanced, programs have become larger and more 
difficult to write and maintain. Structured programming breaks down complex programs 
into simple tasks. The rule of thumb is that if a task is too complex to be described 
simply, then the task needs to be broken down further. When the task is small enough to 
be self contained and easily understood, then the task can be programmed. 

Structured programming gave rise to a number of other movements, Object-Oriented 
Programming being one of the more important ones. A number of languages in the 
1980s begin to pick up OOP features. In 1987 Apple creates a language called 
HyperTalk, used to script HyperCard stacks. This preempted the release of Perl in 1988, 
a stili popular higher-level language that combined popular aspects of C, SED, AWK, 
and CSH (see Eigure 1.4). 

Figure 1.4. The big picture, high-level language family tree 
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Introducing Python 


Python is a high-level, interpreted language originally intended for prototyping or as an 
extension language for C applications. The language is eonsidered to be an interaetive, 
objeet oriented-seripting language. It was designed to be highly readable, uses English 
keywords frequently where other languages use punetuation, and has fewer syntaetieal 
eonstructions than other languages (some eall this elear syntax). Python's history is 
outlined in Figure 1.5. 

Figure 1.5. The Python language family tree 



Python is renown for its use of white spaee, as it uses spaee to delimit program 
statements. The language takes a lot of features from ABC, a language designed with 
beginners in mind, so Python is a great beginning language. Python supports the 
development of a wide range of applieations, from simple text proeessing to WWW 
browsers to games (as we will shortly see). 

Python Features 

Python was developed by Guido van Rossum at the National Research Institute for 
Mathematics and Computer Science (otherwise known as CWI) in the Netherlands. 
Python is copyrighted, but the source code is open source and fireely available. And yes, 
the language is named after the TV series Monty Python's Flying Circus. 

Python's feature highlights include: 

• A broad Standard library, one of Python's greatest strengths. The bulk of the 
library is very portable and cross-platform compatible on UNIX, Windows, and 
Macintosh. The library contains built-in modules (written in C) that provide 
access to system functionality (for instance, file I/O) that would normally be 
inaccessible to a high-level language. Standard libraries include fides, strings, 
math, threads, sockets, CGI, HTTP, and FTP. 

• Support for an interaetive mode in which you can enter results from a terminal 
right to the language, allowing interaetive testing and debugging of snippets of 
code. 

• An extensive graphics package. 

• It is very portable, with interpreters for most operating Systems. 

• Support for OOP in the form of multiple inheritance, classes, namespaces, 
modules, objects, exceptions, and late (runtime) binding. 
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• Support for functional and structured programming methods as well as OOP. 

• It can be used as a scripting language or can be compiled to byte-code for 
building large applications. 

• Very high-level dynamic data types. 

• Dynamic type checking. 

• Automatic garbage collection. 

• Run type checking. 

• It is easily integrated with C, C++, COM, ActiveX, CORBA, and Java. 
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Introducing Lua 

Lua is a byte-code interpreted glue language with extensible semantics as a primary 
feature. Lua is considered lightweight and was designed for extending applications. Its 
predecessors are Smalltalk, Perl, Paseal, and AFNOR, as illustrated in Figure 1.6. Lua is 
considered an excellent language for rapid prototyping and scripting and is implemented 
in C. 


Figure 1.6. The Lua language family tree 



Lua Features 

Lua was developed at TeCGraf, the computer graphics technology group at the 
Pontifical Catholic University of Rio de Janeiro in Brazil. The team credited with 
developing the language in 1994 includes Waldermar Celes, Roberto lerusalimschy, and 
Luiz Henrique de Figueiredo. The language qualifies as open source but it is not in the 
public domain, and Tecgraf holds the Copyright. Lua means moon in Portuguese. 

Lua feature highlights include: 

• A simple Pascal-like syntax. 

• It is dynamically typed. 

• Automatic memory management and garbage collection, 

• Powerful data description constructs like associative arrays. 

• OOP mechanisms such as classes and inheritance. 

• User-controlled type constructors. 

• Fallbacks for extending the meaning of the language in unconventional ways. 

• Its programs are compiled into byte-code and then interpreted, simulating a 
Virtual machine. 
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Introducing Ruby 

Ruby is considered a pure, modern, object-oriented language. Figure 1.7 shows how 
Ruby combined elements of Smalltalk and Eiffel. It sports a simple syntax inspired by 
Perl and Ada and is eonsidered very readable, easy to maintainable, and elean, with only 
a few speeial syntaetieal situations. Ruby is highly portable and runs on UNIX, Max, 
Windows, DOS, OSX, and Amiga platforms. 

Figure 1.7. The Ruby language family tree 



Ruby Features 

Ruby was ereated by Yukihiro Matsumoto in 1993. The language is open souree, and its 
use is eovered under the GPL artistie lieense. Matz, as he is affeetionately known, knew 
Python, but he didn't like it beeause it wasn't pure OOP. He wanted a genuine OOP 
seripting language that was easy to use and write. Ruby's name, however, is a takeoff on 
Perl and is named after a eolleague's birthstone. 

Ruby feature highlights inelude: 

• Pure OOP. Every bit of data in Ruby is an objeet, even basio types. There are no 
Ruby funotions, only method oalls (every funotion is a method). Unified 
olass/type hierarohy, metaolasses, and the ability to subolass everything. There is 
also only single inheritanoe. 

• Dynamio loading. 

• Exoeption handling. 

• Automatio garbage oolleotion. 
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Summary 


You should now feel pretty comfortable describing a high-level language, and you 
probably know enough about Ruby, Python, and Lua to be a source of interesting 
conversation at a local coffee house. You might be able to name a few predecessors of 
each language and have an idea of how eaeh is related (eheek out the big family tree in 
Figure 1.4 to put this history in perspective). You should defmitely understand what a 
scripting language, interpreter, and eompiler are before you go onto the next seetion. If 
you can also pull facts about OOP and open souree, give yourself an A and move on to 
Chapter 2. 

Important points from this chapter: 

• Languages possess a syntax that defmes the order, arrangement, and structure of 
the System of communication. 

• AU computers CPUs have an internal machine language that they execute 
directly. 

• AU data in a modern digital computer is stored as binary on and off States. The 
tools used to manipulate these on/off States are coded in a numerical 
representation, normally consisting of two pieces of Information: operation 
codes and addresses. 

• Assembly language is one step higher than machine language and consists of 
numeric instructions for specific computer architecture. 

• High-level languages act as translators between programmers and low-level 
computer instructions and closely resemble everyday human language, making 
them much easier to learn than their low-level equivalents. 

• Interpreted languages translate code step-by-step during runtime. 

• Compiled languages translate code before a program is run in a process called 
compiling that turns written code into a runable executable or runable byte-code. 

• A scripting language is a high level language designed for "scripting" the 
operation of a computer. 

• High-level languages save human time, low-level languages save computer time. 
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Questions and Answers 


1 : Q: Why would I want to program a game in Python, Ruby, or Perl if C is 
faster? 

A: A: Speed is obviously essential for games, but most of the slowdown of a 
particular game engine oeeurs in only a few plaees. Many eompanies opt to 
do the bulk of their game development in a high-level language, and then 
delve deep into C or assembly for speeifie, proeessor-bogging graphies. 
Python and Ruby were designed with this mind, so they lend themselves well 
to extending themselves in C or any other language. Lua itself is ereated with 
C, and ean also work with that family quite easily. 

2: Q: What types of games are usually developed with these languages? 

A: A: Python has been the engine behind a number of tities but is widely known 
for allowing eompanies to easily and quiekly ereate graphieally rieh, Myst- 
like worlds, and eartoon-animated games like the award-winning tities firom 
Humongous. It is also the glue behind a few major motion pieture CGI shops, 
used in various ways for eomputer graphies produetion. Lua has been a 
hidden seeret of game eompanies for a deeade and has been the seripting 
agent behind a number of popular games on platforms ranging firom 
handhelds to PCs to the Xbox. Normally Lua is used for game seripting, and 
not the game engines themselves. Ruby is stili gaining in popularity, and 
many of its larger game projeets are stili in development. Until reeently, Ruby 
was regarded mostly as an all-purpose OOP language, and mueh of its 
development thrust has been in enterprise-level Internet applieations. Ruby is 
eapable, however, of the same sorts of game development that Python is and 
has a few extremely strong graphies and sound toolkits and libraries. 

3: Q: Why is it easier to find projeets with Python and Lua than with Ruby? 

A: A: Ruby is just as pervasive as the other two languages, exeept that the bulk 
of development and doeumentation is happening in Japan. Ruby enthusiasts 
elaim that the language is mueh more popular than Python in Japan, whieh is 
evident by the growing number of Ruby books that are available in Japanese. 
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Exercises 


1: Answer the following as True or False: 

A. High-level languages are diffieult to port to other arehiteetures. 

B. High-level languages are ealled high-level beeause they resemble 
human languages. 

C. Programming languages are translation Systems. 

D. The biggest problem with low-level languages is adapting them to 
different platforms. 

2: Fili in the blanks in the following sentenees: 

A. A eomputer program that eonverts assembly language to maehine 

language is ealled a(n)_. 

B. A eomputer program that translates eode during the program_ 

ealled an interpreter. 

C. An example of a high-level language besides Python, Ruby, or Lua 

is_(give at least two examples). 


3: What is the only language that a eomputer ean understand direetly? 

4: Imagine your ideal programming language. Make a list of ten must-have 
features that your perfeet programming language would possess. 

5: Deseribe the differenees between high-level, interpreted, and seripting 
language features (I warned you there was a quiz eoming up)! 



Chapter 2. Python, Lua, and Ruby Language Features 

The limits of my language means the limits of my world. 

-Ludwig Wittgenstein 

This chapter serves as an introduction to common features of Python, Lua, and Ruby. I 
introduced each language in Chapter 1, and in this chapter TU be going into more details 
of the languages. 

There are two main goals for the chapter. The first is to give you a foundation for 
leaming how to use these languages by covering a few features they have in common. 
The second objective for this chapter is to start you coding. 

These objectives are met in the main sections within this chapter. The first section 
covers a few of the common base programming commands the languages have in 
common. The second section walk s you through a "Helio World" sample in each 
language. 
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Syntactical Similarities of Python, Lua, and Ruby 

One great bonus to learning similar languages at once is the overarching familiarity that 
comes with common elements. AU programming languages have some similar features, 
and these three languages in particular are based on similar premises and ideas. This 
makes it possible to share the learning curve, so to speak. Python, Lua, and Ruby share 
the following particularly important programming elements: 

• Comments and commenting 

• Math and algebraic functions 

• Variables 

• Lists and strings 

• Program structure 

Comments and Commenting 

AU modern programming languages allow programmers to insert comments into their 
code. Comments are extremely important, not only to the professional who needs to 
write code that other people may need to change or maintain, but also to individuals or 
independent programmers who need to look at their code again at some point in the 
future to see how they did something or modify an existing program. 

Most languages reserve the use of the pound sign (#) to designate a one-line comment. 
You will fmd the # Symbol used in this way in AWK, Perl, PHP, and C, but most 
importantly for us, in both Python and Ruby. Here is an example of commenting in 
Python and Ruby: 

PYTHON 

RUBY 

# This code sample has only comments 

# The computer, compiler, or interpreter will for the most part 

# Ignore ali of these lines 

# Simply because they start with a pound sign 


Lua has its very own comment designator: two dashes in a row (—). Here is an example: 

LUA 

-- This code sample has only comments 

-- The computer, compiler, or interpreter will for the most part 

-- Ignore all of these lines 

-- Simply because they start with dashes 


Math and Algebraic Functions 

When it comes right down to it, your computer is speaking a language of Os and Is. It's 
no surprise, then, that math tools, functions, and operators tend to be similar across ali 
languages. You can pretty much bank on functions like add (+), subtract (-), multiply 
(*), and divide (/) being available no matter what programming language you are using 
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Another commonality between Python, Lua, and Ruby is using parentheses () to state 
precedence; this comes right out of high school algebra. For instance, the answer to this 
code example will be different depending on the order of operations: 1+2*3 = X. 

If you perform the operations from left to right, X will equal 9, but if you do it from 
right to left, X will equal 7. Python, Lua, and Ruby (along with many other languages) 
use parentheses to specify the order in which computations should be performed if you 
wish to override the natural order of operations. If you needed to specify that you 
multiply before adding in the following example, you can use parentheses around the 
multiplication, forcing the multiplication to be computed before the addition: 

1+ ( 2*3 ) = X 


Parentheses are often used with other programming structures to perform comparisons 
and to make decisions during the program flow. Understanding how to pose and 
evaluate comparisons is a crucial skill for any programmer or computer scientist. 
Because they are so often used, many different types of comparisons have been 
developed. 

Boolean Logic 

A mathematician named George Boole invented Boolean algebra in the nineteenth 
century. Boolean Algebra only has two values: True and False (this is sometimes called 
two-valued logic). It may be difficult to balance your checkbook with Boolean algebra, 
but if s extremely easy to create decision and logic trees with it. 

Boolean expressions often involve comparison operators to help evaluate truth or 
falsehood. Operators such as equal (=), less than (<), and greater than (>) should look 
familiar to you if you didn't skip your high school math classes. These constructs are so 
common and useful that many languages use them. Python, Lua, and Ruby all use the 
same comparison symbols, illustrated in Table 2.1. 

Comparison operators are normally used to form expressions that can be evaluated as 
True or False. For example; 


1 

< 2 

- Evaluates 

to 

TRUE 

1 

> 2 

- Evaluates 

to 

FALSE 

1 

= 2 

- Evaluates 

to 

FALSE 


Sometimes you need to make comparisons in groups. A program may need to ask, "Is 
player character one an Elf AND a Wizard?" 

Playerl = (Elf AND Wizard) 


Typical comparisons use logical structures: logical AND, logical inclusive OR, and 
logical NOT. Logical AND along with logical OR are used to combine conditions or 
statements. Lua and Python try to keep the constructs simple for the reader by using 
common English words, as do most high-level languages, including Eiffel, Ada, 
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Smalltalk, Lisp, and Perl. You can designate logieal AND, OR, and NOT by using the 
eommand words and, or, and not, respectively. 

Ruby takes a slightly different course and follows eonvention, using the same 
programming symbols that the popular C family (C, C++, and C#) uses to designate 
AND, OR, and NOT; &&, ||, and !. These differenees are also illustrated in Table 2.1. 

The logie eonstructs AND, OR, and NOT are normally used with Boolean True and 
False to form simple and complex programs. These eonstructs are sometimes called 
Boolean operators. 

Boolean operators are evaluated differently when in combination with each operator. 
For the AND operator, the combination of two True values results in True; all other 
combinations evaluate to False, as illustrated in Table 2.2. 


Table 2.2. Boolean AND 


Operators 

Evaluation 

True AND True 

Evaluates to True 

True AND Ealse 

Evaluates to Ealse 

Ealse AND True 

Evaluates to Ealse 

Ealse AND Ealse 

Evaluates to Ealse 


For the OR operator, as long as one of the values is True, then the expression evaluates 
to True, as shown in Table 2.3. 


Operators 

True OR True 
True OR False 
False OR True 
False OR False 


Table 2.3. Boolean OR 
Evaluation 

Evaluates to True 
Evaluates to True 
Evaluates to True 
Evaluates to Ealse 


The NOT operator is called the complementary operator. It reverses the truth-value, as 
shown in Table 2.4. 


Operators 

NOT True 


Table 2.4. Boolean NOT 

Evaluation 

Evaluates to Ealse 
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Table 2.4. Boolean NOT 


Operators Evaluation 

NOT False Evaluates to True 

Once you understand Boolean logic, comparison operators, and logieal structures, you 
can create very complex decision trees, like this: 

# The following line evaluates to Boolean FALSE 

(((l+2)*5) =11) and ((5*6) != (7*6)) 

# The Following line evaluates to Boolean TRUE 

((1 + 1) = 5) or ((5*6) = 40 and ((5/4) = 2*.5)) or ((50/5) = 10) 

Table 2.1. Common Math Functions in Python, Lua, andRuby 
Function Python Command Lua Command Ruby Command 


Add 

+ 

+ 

+ 

Subtract 

- 

- 

- 

Multiply 

* 

* 

* 

Divide 

/ 

/ 

/ 

Equal (assignment) 

= 

= 

= 

Equal To 

== 

== 

== 

Eess Than 

< 

< 

< 

Greater Than 

> 

> 

> 

Eogical NOT or Not Equal To 

not 

not 

! 

Eogical AND 

and 

and 

&& 

Eogical OR 

or 

or 

II 

Square Root 

sqrt 

sqrt 

sqrt 

Exponent 

exp 

exp 

exp 

Absolute Value 

abs 

abs 

abs 

Basic Sin 

sin 

sin 

sin 

Cosin 

cos 

cos 

cos 

Tangent 

tan 

tan 

tan 

Eogarithm 

log 

log 

log 

Truncate/Round 

round 

round 

round 

Eloor 

floor 

floor 

floor 

Ceiling 

ceil 

ceil 

ceil 

Power 

** 

A 
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Variables 


Computers and computer programs manipulate data. Variables are holders for data any 
eomputer or program might need to use or manipulate. Variables are usually given 
names so that a program ean assign values to them and refer to them later symbolieally. 
Typieally a variable Stores a value of a speeific given type like; 

• An integer or whole number 

• A real or fraetional number 

• A eharaeter or a single letter of an alphabet 

• A string or a eolleetion of letters 

Many languages need to know in advanee what type a variable will be in order to store 
it appropriately. Sinee eomputers are finite in memory, there are often several different 
numerieal designations, depending upon how big a number ean grow or how that 
number needs to be represented in binary. 

Others languages are more flexible in dealing with variables; this is called dynamic 
typing, as I mentioned in Chapter 1, and is a eommon high-level language feature. Even 
with dynamie typing, most programmers deelare variables at the start of their program 
out of eonvention. This eonsists normally of dreaming up a name and then deelaring a 
data type for the variable. Typieal variable types are listed and deseribed in Table 2.5. 


Variable type 

Boolean 

Float 

Integer 

Null 


String 


Table 2.5. Typieal Variable Types 
Description 

Holds only True or False 

A number with a deeimal point (floating deeimal point) 
A whole number 
No value 

Ordered sequenee of eharaeters 


Eaeh language's variable types and how to use them are explained in more detail in their 
respective seetions in this book, but there are a few eommonalities I will mention here. 
For instanee, null values are symbolized by nil in both Fua and Ruby, while Python 
uses the designation none. Both nil and none are treated as false in a Boolean sense. 

PYTHON 

# This assigns x a null or Boolean false value in Python 
X = none 

RUBY 

LUA 

# This assigns x a null or Boolean false value in Ruby or Lua 
X = nil 
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A second example of similarity with variables is that Python and Ruby both use the 
value method to grab the value of a variable. 

PYTHON 

RUBY 

# this code snip uses the value method to 
return the value of x 

X = 4 

# This line grabs x and prints it in Python 
print X. value 

# This line grabs x and prints it in Ruby 
Sstdout.print(x.value) 

NOTE 

CAUTION 

Many popular languages—for instance C, C++, and Perl—also use zero (0) as Boolean 
false. This is not necessarily the case in High-Level Land. For instance, in Ruby, 
anything not designated as nil or false is automatically true in the Boolean sense, 
even the number 0. This switch sometimes tricks converts from other languages. 

Although similar in some ways, Python, Lua, and Ruby differ significantly in how they 
handle variables and types. They each follow slightly different paradigms that create 
differences on a basic level. These differences will become apparent as you delve into 
each language in the chapters that follow. 

Lists and Strings 

Lists are used to group things together. They are data structures designed to make life 
easier for the programmer. A list is simply a row of variables or data elements. They can 
be composed numbers, letters, or even constructs such as arrays, hashes, or even other 
lists. Lists are created in Python and Ruby by using brackets [ ]: 

PYTHON 

RUBY 

#To create a list called lista with the numbers 1 through 10, just put 

them in brackets 

and separate them with commas: 

lista = [1,2,3,4,5,6,7,8,9,10] 


You can use the + Symbol in each language to concatenate lists together: 

PYTHON 

RUBY 

# To combine fish and chips list a with list b 
lista = [1,2,3,4,51 

listb = [6,7,8,9,10] 

# Just add them together into a new list 
newlist = lista+listb 
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Since not all languages have direct support for strings, one of the time-saving features 
that high-level programmers often enjoy is built-in string handling. Not only are there 
common commands for working with strings, the memory management of strings is 
usually handled automatieally. 

A strings is basically just a list of charaeters. To get Lua, Python, or Ruby to reeognize 
a string verbatim, you ean place it between single parentheses, like so: 

PYTHON 

LUA 

RUBY 

# Python, Lua, and Ruby will reeognize this as a string 
'Enclose strings like this in single quotes' 


You ean also use math functions to make string comparisons in Python and Ruby, just 
like you ean with lists. For instance, the + sign ean be used for string concatenation with 
Python or Ruby, like so: 

PYTHON 

RUBY 

# to combine the strings 'fish', 'and', 'chips' 
stringa = 'fish' 
stringb = 'and' 
stringe = 'ehips' 

stringd = stringa+stringb+stringe 


You will find that equal to (==) and not equal to (! =) are often used to compare different 
strings as well: 

PYTHON 

RUBY 

# Is the password 'Enter' ? 

# First, get the password 
If password = 'enter' 

# Then you shall pass 

If password != 'enter' 

# Then no sueh luek 


Arrays 

Arrays are similar to lists. They are both used for storing items or lists of items, but they 
keep track of the items in different ways. Arrays organize lists of items by a numeric 
index, an extremely powerful tool in programming. 

Although each of these languages handles lists in a similar way, they have somewhat 
different approaches for arrays. Ruby has a built-in array method, but, strictly speaking, 
Lua does not have built-in arrays and substitutes for them with table structures. Python 
has its own version of arrays called sequences. 
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Despite the differences, these languages handle arrays in similar ways. An example is 
the sort method or command. Ruby uses sort to put in order items within a hash or 
array, Lua uses sort to order a table, and Python uses sort to order a list. Similarities 
like these run deep through these languages, but ean beeome eonfusing and difficult to 
wade through when switching between them frequently. 

Program Structure 

AU programming languages have some sort of structure or flow to them. Most programs 
share a structure similar to that in Figure 2.1. Normally there is a statement that 
establishes the beginning of a program, then variables are declared, and then there are 
code blocks, which are also called program statements. 

Figure 2.1. A typical program structure 



i 
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Program statements provide the control of a program. They usually act as decision trees, 
executing different sections depending upon the input given. Figure 2.2 illustrates a 
structured-programming graph in which the ovals represent starting and ending points, 
the squares represent program blocks, and the diamond represents a decision to be made 
in the program that will send the flow down one of two branches. 

Figure 2.2. A structured-program fiowchart 
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Program statements come in a couple of different forms. So far in this book, fve used 
mostly simple statements. Simple statements are short expressions that perform specifie 
actions. There are also compound or complex statements that generally consist of more 
than one line of eode and use many expressions. 

Statements that control whieh sections of code are to be exeeuted are called control 
statements (surprise!) and eonsist of a few basic types. 

• Linear Control Statements. Control is based on a logical sequence, and eode is 
exeeuted in the default order as if s listed in the source file. 

• Conditional Control Statements. A condition is set that makes a deeision on 
whieh block of code is to be exeeuted. 

• Iterative Control Statements. Blocks of eode may be exeeuted more than once 
in loops. 

Linear Control Statements 

Linear eontrol statements are the most intuitive of type of program structure. In linear 
control, commands are exeeuted in a sequential, ordered, linear manner. This usually 
equates to running one line at a time, like so: 

Start Program 
Run Command 1 
Run Command2 
Run Commands 
End Program 
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Since English-speaking humans are most comfortable reading from left to right and 
from the top down, the same conventions are used in linear eontrol. 


Conditional Control Statements 

Statements that are considered eonditional are often referred to as if/else statements. 

The commands if and else determine which lines or blocks of eode might or might not 
run, depending on the flow of the program. Programmers generally use these as 
branehes to initiate actions that are dependent on user input. 

The if eommand is the foundation of all eonditional statements. if cheeks a specified 
condition for truth value. If the eondition is true, then if executes a eode bloek that 
follows. If the condition is not true, the eode bloek is skipped. 

if (this condition is true) 

(then this happens) 


Figure 2.3 depicts the flow of a program going through an if statement. The flow goes 
through the diamond branch, which executes the eode bloek (the square) if the condition 
is true or continues to the ending oval if the condition is false. 

Figure 2.3. A generic example ofa program flowing through an ±f statement 



Python uses if for eommand flow in the following way: 

PYTHON 

# Examples of and if statement checking the truth of X being greater 
than 90 in Python 
if X > 90 
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Then do this 


Ruby and Lua are similar, but use an end eommand to designate the end of an if 
strueture. 

RUBY 

LUA 

if X > 90 
then do this 
end 


The else eommand is another eommon eonditional that ean follow an if statement. 
When an if statement returns a value of false, the eode bloek held by else exeeutes. 
This ereates a fork in the program, where either the if bloek or the else bloek is 
executed. When using else and if together in Python, Ruby, or Lua, the general syntax 
looks something like the following; 

if (this condition is true) 

then this happens else (this happens instead) 


This series of if and else statements allows eode to make deeisions based on variables 
or input. When the program flow has two possible execution ehoices, it is known in 
struetured programming as a double seleetion. The if/else statement is illustrated in 
Figure 2.4. 

Figure 2.4. The top-down flow of an if/eise statement. The false and true 
branches both execute blocks ofcode 
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A double selection can be limiting because there are only two forks that the program 
can take. If you need to program for multiple paths, you ean use the elsif command in 
Ruby, the elseif command Lua, or the elif command in Python, ali of which are 
equivalent. 

You can use multiple elsif/elif statements in a row to create one long string of 
conditions for which to check. However, only one else statement can follow an if. The 
syntax for these statements looks like the following; 

if (this first condition is true) 

(then this first program block runs) 

elsif/elseif/elif (this second condition is true) 

(then this second program block executes) 
elsif/elseif/elif (this third condition is true) 

(then this third program block runs) 
else 

(this fourth block fires instead) 


As we get deeper into each language, each will start to have its own distinet flavor, and 
they will begin to appear different. You can see how different in the following code, 
which displays the typical elsif/elif/elseif flow in each language. Figure 2.5 also 
shows a typical elsif/elif/elseif program structure. 

Figure 2.5. Structure of a program illustrating multiple eise/if branches 
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# Example of elsif in Ruby 
if X > 90 

then this blocka fires 
elsif X < 90 

then this blockb fires 


else 


blockc fires 


end 


Iterative Control Statements 

Programming languages must have a facility to allow sections of code to be repeated, or 
iterated. Iteration is possibly a computer's greatest strength. There are several variations 
of eonstruets that are used to iterate program bloeks; these are eommonly ealled loops. 

The for Loop 

The for loop is probably the most oommon loop in programming. It takes a few 
separate eonditions to exeeute and takes on the following general strueture: 

for (the length of this expression) 

(exeeute this code block) 


Figure 2.6 shows the stmetured program flow of a for loop. Notiee that there are two 
programming bloeks: the first is the eode that exeeutes as part of the loop expression, 
and the seeond is the bloek that the loop exeeutes. 


Figure 2.6. The flow ofa for loop 
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Although iteration commonly is needed when programming, and a built-in for 
construet exists for each of these languages, each has its own peculiarities. 

Python's for loop uses a counter and a range to determine how many times to loop a 
given code block. The counter is incremented eaeh iteration of the loop until the counter 
reaehes the end of the range and the loop is complete. 

PYTHON 

for counter in range ( X ): 
block 

To create a for loop in Python that loops 10 times, do the following: 
PYTHON 

for counter in range ( 10 ) : 
block 


Lua's for statement works in the same prineipal way but has two forms, one for 
numbers and one for tables. The numerical for loop has the following syntax: 

LUA 

for name '=' expl ' exp2 ' exp3] do block end 


The first expression (expl) is the eounter, the seeond (exp2) is the range, and the third 
(exp3) is the step (the step is automatieally a step of 1 if omitted). Therefore, a for loop 
in Lua that would run a block 10 times would look something like the following: 

LUA 

for name = 1 ,10, 1 do block end 


Ruby has a unique way of dealing with for loops, and iterators in general. Ruby uses a 
number of predefined classes with built-in methods to provide iteration funetionality. 
There are several ways to accomplish the same 10-iteration loop in Ruby: 

RUBY 

10.times do 

block 

end 


Or 

RUBY 

1.upto(10) do 
block 

end 


Ruby also has a eomparable for/in construet with a similar structure: 

RUBY 

for i in 1..10 
block 
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end 


and a built in loop iterator that looks this: 

RUBY 

i=0 

loop do 

i += 1 

next if i < 3 
block 

break if i > 4 
end 


The while Loop 

A second common loop is known as the while loop (sometimes known as the do/while 
loop). A while loop is normally used to keep a section of code continually running 
while a certain condition is true. The flow of this loop is shown in Figure 2.7. 

Figure 2.7. A flowchart thatillustrates a typical whiie loop 



The while loop takes on the general structure of: 

while(this statement is true) 

do (execute this block) 


Each language, again, has its own nuances, but the while loop looks fairly similar in 
each. 
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Python's while loop is almost identical to the for loop: 


PYTHON 
X = 100 

while X < 100: 

block 


Note that these examples could execute a never-ending loop unless a way to increase x 
was added. 

Lua's while is almost identical to Python's, but with substitution of parentheses for the 
end colon and the addition of an end: 

LUA 

while ( X> 100) do 

block 

end 


Ruby's while is also almost identical to Python's: 

RUBY 

while X < 100 
block 

end 


Miscellaneous Similarities 

As you read through this book, you will find more and more similarities between the 
languages. In addition to commenting, mathematics, lists, variables, and program 
structure, there are a number of other significant similarities. Some of these I will point 
out as the book progresses, and others you'll discover on your own. A few of the more 
significant ones are illustrated in this section. Table 2.6 lists a few miscellaneous 
commands that have similar or the same names. 


Table 2.6. Similarly Named Commands 


Function 

Python 

Command 

Lua 

Command 

Ruby 

Command 

Access read/write 

a [e] 

a [e] 

a [e] 

Runtime evaluation 

eval 

dostring 

eval 

Duplicate n times (string 
repeat) 

■k 

strrep 

■k 

ascii to character 

chr 

strchar 

chr 

Value 

V 

V 

V 
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End-of-Line Characters 


Knowing where a command line ends is important for understanding program flow. One 
line of eode is usually over at the end of the line, when a retum is entered. The end of a 
line may also end in an "End of line" command such as a colon (): or semicolon (;). 
Python and Ruby both use the semicolon Symbol as an end of line command to end a 
statement; in Lua the semicolon is optional. In Python and Ruby you can also simply 
use an end of line character (or a return). 

# Sample of an end of the line statement 
This code line ends at the semicolon; 

This is a second, separate line of code; 


Breaking up a line is useful if the line is too long and you need to go on to the next line. 
Both Ruby and Python both use the \ (backward slash) to signify that the command goes 
on to the next line. 

PYTHON 

RUBY 

# Sample of using a \ to extend a line of code 
This code line ends at the semi colon; 

This snippet goes on to the next line\ 

And ends here 


OOP structure 

Since each of these languages is object oriented to some degree, and they are ali based 
on similar strategies, it follows that they possess similar object-oriented constructs. This 
is especially true for Python and Ruby, whose commands for method invocation, class 
declaration, and scope are identical. In fact, method invocation (and scope) uses a very 
recognizable structure for OOP veterans: 

obj ect.method(parameter) 


As you can see, the . operator is used to defme scope as well as a record selector. The 
command class is also used to designate a class in both languages. 

Function Calis 

AU three languages have similar commands for function calls, the typical syntax being: 


function(parameters) 


In Ruby, you can call a function without any parameters just by naming it: 


function 
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In Lua and Python, you must stili specify that there are no parameters with parentheses: 

function () 


The command return is used by Ruby and Python to break the function control flow 
and retum a value. 
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Helio World Samples 

Now that youVe seen snippets and small samples of code, it's time to look at what a 
fiilly functioning program looks like in each language. 

Programming in each language is explained in depth in each of the following sections, 
so don't be concemed if the code sample that follows appears foreign. This is just a 
sample to whet your appetite. 

The Python Environment 

Python is at horne in a number of different environments and can be programmed via 
command line, script, or debugger. This section will help you install Python on your 
System and will demonstrate the different options available when you need to sit down 
and write code. 

Installing Python 

This book's CD-ROM comes with the tar archive and the Windows installer for Python 
Version 2.2.2 (released in October of 2002); you can find them in the Python folder. 

You can also download Python installers for a number of other different platforms firom 
the Python.org Website at http://www.Pvthon.org/download . 

As of this writing, Python 2.32 alpha is available firom Python.org in Windows. The 
alpha is also included on the CD, but the samples in this book were written with Version 
2 . 22 . 

Simply double-clicking on the Python-2.2. 2.exe file located on the CD under \PYTHON 
will run the Windows installer. The installation is fairly straightforward; just click OK 
on the Windows that pop up (see Figure 2.8). 

Figure2.8. The Windows Python Installer in action 
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If you'll be installing for a UNIX platform, you'll need to perform the regular steps for 
unzipping the tar archive and installing (gunzip,tar, . /conf igure, make, and make 
install). You will want to perform this action as root. 

If you'll be installing Python on a Macintosh, you will want to use the 
MacPython222Full.bin file for OS 8.6 or higher—except for OS X. For OS X, you will 
want to use the Standard tar archive. If you are running Mac OS X 10.2 or later, Python 
actually ships on the platform, and you won't need to install it at all. Python for the 
Macintosh is maintained by an independent programmer named Jack Jenson. You can 
find patches for a few older Mac operating Systems and more information at his Website 
at http://www.cwi.nl/--iack/macpvthon.html . 

If you are running Red Hat and want to grab the RPM sources instead of using the tar, 
they are available for some distributions from Python.org. Just go to the Website and 
check out the Download page. 

If you do decide to use a version of Python other than 2.2.2, be sure you use Version 2.0 
or higher. Python went through a few significant changes from Version 1 to Version 2, 
and if you use a version earlier than 2.0, you may have trouble running the code 
samples in this book. 

The Python language is copyrighted by Stichting Mathematisch Centrum in Amsterdam. 
However, it is free to use, copy, modify, and distribute and is OSI (Open Source 
Initiative) certified. You can find a copy of the license and Copyright in the Python 
folder on the accompanying CD, and again in the Licenses folder. 

NOTE 

CAUTION 
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Intellectual-property attorneys exist for a reason: It is possible to get in legal trouble 
selling open-source Software. Luckily, the open source community is fairly watchful 
about intellectual property law, and licenses are becoming somewhat Standard and 
easier to read. There are risks assoeiated with ineorporating open souree eode into 
eommereial endeavors that should not be taken lightly but these risks should not prevent 
you or your company from using this viable and effective resource. If you have 
concerns or questions about a license, or about using any open source Software in a 
major enterprise, by all means ask an expert. 

Running the Python Interpreter 

After youVe installed Python on a Windows machine, the Python interpreter is 
accessible via the run command. Simply do the following: 

1. Open your Start menu. 

2. Select Run. 

3. Type python and hit OK, as illustrated in Figure 2.9. 

Figure 2.9. Windows XP waits for a command from the user to launch 

Python 


fV ri n prTtqrfiTk, friVt. «iriimer*. or 
Intoirflt restxrce and ml t for you- 



You will get a command window that looks like Figure 2.10 saying: 

Figure 2.10. The Python interpreter awaitsyour command 
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Python 2.2.2 <#37, Oct 14 
win32 

Type "help", "Copyright", 
>>> 


2002, 17:02:34> [MSC 32 bit <Intel>] on 
"credits" or "license" for more Information 


NOTE 

CAUTION 

The Python installer tries in good faith to set your machine path variables so that you 
can run the Python binaries from the command line or anywhere else for that matter, but 
the installer may not be able to on your partieular platform. If you eannot get Python to 
launeh from the eommand line, you may have to set the path variables yourself or 
simply run the Python (eommand-line) entry that is added to the program files listing 
under Python 2.2. 

On a UNIX system, the Python interpreter is usually installed as /usr/loeal/bin/python, 
but of eourse where the interpreter lives is an installation option left up to you. You will 
need to put /usr/loeal/bin in your UNIX shelfs seareh path to make it possible to start 
the interpreter by typing the eommand python to the shell. 

The Python interpreter actually operates somewhat like a UNIX shell—it reads and 
exeeutes eommands interaetively. The interpreter ean also be ealled with a filename 
argument or with a file as Standard input. 

Go ahead and test out the interpreter. You ean start by executing various one-liners like 
print "hello world" or 5*5. The interpreter is great for testing out eertain funetions. 
The interaetive help is also very useful. Type the following at the interpreter's prompt: 

>>> help (list) 


You will reeeive information on the list eommand, its syntax, and samples of its use 
(as illustrated in Figure 2.11). 

Figure 2.11. Python '§ interpreter shows how to use the built-in iist class 

object 
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In this mode, which is called Interactive mode, you can type any Python command and 
it will work just as if you typed it from a script (with a few differences). If you type a 
command that returns a value of some sort (except assignments), the interpreter will 
print the resuit automatically. This is great for experimenting and for testing a specific 
language feature when you need to get the syntax right. The interpreter isn't very 
helpful, however, when it comes to large sections of code or actual programs, which 
you will want to write and then execute at once. 

What the interpreter is quite good at, though, is running through the code snippets and 
short examples you'll find in the next few chapters. You can easily run one-liners to test 
a particular Python feature, or you can write short, multiple-line code snips by first 
using a colon and then tabs to delineate a code block (as illustrated in Figure 2.12); 

Figure 2.12. The Python interpreter is poised to run this Uve-iine code 

snippet 


CrirythonPJVPython.txtt 

Python 2.2.2 CS17« Oi:l. Id 17:n3:li> IHSC 32 hit c|ntv]>l nn win32 
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»> if 1 > 2: 

... N Tlie colnn 
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... H Cr««tes « code block 

... tl In t W I n erproter 

... print *’l is Greater tKan 2" 



To exit Python's interpreter, hit Ctrl-Z on Windows and then press the Enter key, or in 
UNIX, hit Ctrl-D. 

NOTE 
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TIP 

When a script file is used, it is sometimes useful to be able to run the script and enter 
into interactive mode afterwards. You ean do this by passing the -i (i is short for 
"interaetive") argument to the seript. 

NOTE 

TIP 

When you use Python interaetively, you ean set Standard eommands to exeeute every 
time the interpreter is started. You ean do this by setting the environment variable 
PYTHONSTARTUP to the name of a file eontaining the eommands (this is similar to the 
•profile feature in UNIX). This file is only read in interaetive sessions, not when Python 
reads eommands from a seript. 

Creating Python Program Files 

You ean also run Python programs from a file. The usual extension for a Python 
program is .py. To ereate new Python program fde, just fire up your favorite text editor, 
type in a few eommands, and save the program as something .py. For instanee, on 
Windows, open up Notepad and type in: 


print "Helio, World!" 


and save the file as hello.py. You ean then save the file to disk, open up your eommand 
line, browse to hello.py, and run it, as shown in Figure 2.13. 

Figure 2.13. A Python program file runs on Windows 
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You ean ereate Python program files on other operating Systems just as easily, exeept 
that in a Posix environment (UNIX or Finux), you will need to inelude a line at the top 
of eaeh file that points to where Python is installed on your system, like this: 
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#!/usr/local/bin/python 


This makes the file directly executable, like any other shell script. 

Python's "Helio World" 

A Python "Helio World" looks like this: 


#!/usr/bin/python 
############ 

# HELLO_PYTHON_l.py 

# This program displays the string "hello" . 

# It first shows the path to python, then creates a short loop, and 
then prints the 

string. 

############ 
while (1) : 

print "Hello!"; 


Most of this seript is made up of eomments. Python ignores lines that start with the # 
Symbol, so eoders ean plaee their eomments and notes in the source eode. The one 
exeeption to this (and you will find that there are few exceptions in Python) is the very 
first line of eode in this sample. The # i /usr/bin/python eommand lists the path to the 
Python program files so that when the seript is run, the eomputer knows where Python 
resides. This line is optional in Windows, but is normally required when running on a 
UNIX environment, and so it is ineluded here. 

Following the path and the eomments is a short while loop. This line says, "Do 
whatever follows once." Then the print instruction follows. Notice that the print line is 
offset, or tabbed inwards. White space in Python actually serves a purpose; it plaees the 
print eommand within the jurisdietion of the while loop. Also notiee the semieolon at 
the end of that line. Semieolons, as youVe learned, are used to end a statement. 

This source eode ean be found in the \CHAPTER2 folder on the accompanying CD. If 
you run the program, you will see "Hello!" printed to the screen. 

C’s "Hello World" 

For comparison, lefs see what Hello from C would look like. There are many different 
ways to get C to print a string, but typically the effort looks like the following: 

############ 

# HELLO_C_l.cpp 

# This program displays the string "hello!". 

# It first Includes the stdio.h library, then creates a main, 

# then creates a short loop, and then prints the string. 

############ 

#include <stdio.h> 

main () 

{ 

for (;;) 
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{ 

printf ( "Helio!\n"); 

} 


The comments are the same as in Python, but besides the eomments you can see that the 
program is very different. First, C doesn't have a built-in print function, so you need to 
import a library that does. stdio.h is short for Standard Input and Output. The library is 
Standard and comes with most C compilers, but it will add a significant amount to the 
compiled binary. 

Second, every C program needs a main statement, a place for the main program picee to 
run in. This means that main () must be declared before you can proceed any further. 
Then come the squiggly brackets {}. C uses brackets to separate blocks and section of 
code. Whatever is in main must be bracketed by squiggly brackets. 

Then comes the loop (in this case a for loop), which serves the same purpose here as 
Python's while loop; the syntax is, of course, different. Again, squiggly brackets are 
needed to bracket off what belongs within the for loop. 

Finally, we get to printf, a command from the stdio.h library that prints input to the 
screen. Notice that the string must be between both the parentheses () and the quotation 
marks There is also the semicolon (;) that follows the end of a statement, something 
in common with Python. The \n is actually an escape sequence that creates a new line 
once the "Helio!" is printed. 

The key thing to notice is that with C there are a few extra steps: 

• A library that can work with strings must be imported. 

• There must be a main (). 

• Brackets {} must separate code blocks. 

Also look at the syntax. Any missed colon, semicolon, parenthesis, bracket, slash, or 
pound sign will resuit in a program error. Python's code has fewer symbolic syntax 
needs because the designers wanted something that would be easy to write and read. 

The Lua Environment 

The idea behind Lua is that it is to be used as a lightweight configuration language for 
any program that needs one. It is written in clean C, which means the Lua source code is 
made up of the most common subset of ANSI C and C++. Since this section is about 
Lua and this book isn't a book on C, I won't spend a lot of time going over any C code. 
If you want a primer on the C language, I suggest picking up a book on C; there are 
hundreds to choose from. 

Lua is implemented as its own library. If s purely an extension language, and so it has 
no "main" loop of its own. Lua normally functions embedded within a host client, like C 
code or a C program. It is the host program that invokes Lua code, reads and writes Lua 
variables, and so on. Lua can also be extended by C and C functions. We'll look more at 
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combining Lua and C (and Lua's C API) in the next chapter, and we'll examine 
extending Lua, Python, and Ruby in Chapter 12. 

The use of C in this book is actually pretty infrequent. In fact, ali the code samples in 
this chapter should run fine in the Lua interpreter alone. If you come across something 
in C that doesn't make sense, don't get nervous; just move on. Eventually, ali code will 
succumb to your will and prowess. 

Normally Lua is used within a host language, and usually the host language is C. Lua 
can also be used alone, usually for quick glue programs or text-processing Utilities. 
These standalone projects tend to rely heavily on the basic libraries Lua provides. 
Finally, there are applications that use Lua as a library. These apps tend to have more 
program code in C than in Lua, and they create interfaces to the Lua language within C. 

In this chapter, almost all of the examples are pure Lua and can be run with the Lua 
interpreter. Using Lua within a host language or library is covered more in the next 
chapter, where I get down to using Lua in a game-programming environment, and also 
in Chapter 12, where TU discuss extending and embedding high-level languages. 

Installing Lua 

Lua is firee Software, and the license is included in the CD folder (under Lua) along with 
the necessary packages for building and installing Lua 5.0. This includes a generic 
tar.gz for building Lua from scratch on most platforms and an .rpm (Redhat Package 
Manager) for Linux Red Hat. You can build Lua from the source on any UNIX-fiavor 
machine with the provided make files. 

In order to build Lua from the source on a Windows machine, you need a development 
environment like Visual C++ 6.0 or Cygwin, but luckily for you, the precompiled win32 
executables and binaries are included in the LuaWin32.zip file. Instead of your building 
Lua from scratch, the zip file will provide a lua.exe executable that starts up the Lua 
Interpreter. 

NOTE 

CAUTION 

The preconfigured lua.exe and luac.exe binaries are statically linked, so when 
developing real projects you will want to place these within the bin folder of the full 
Eua source tree. The libraries included should also be placed in the Eua lib folder so that 
they can link with one another. See the documentation on installing Eua at 
http://www.lua.org 

Lua 5.0 was released in April 2003. Some new features in 5.0 include: 

• Coroutines (collaborative multi-threading) 

• Full lexical scoping (replaces upvalues) 

• Metatables (replaces tags and tag methods) 

• Support for true / false Booleans 

• Weak tables 
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• New API methods 

• New error handling techniques 

The original Lua language (Version 1.1) was first publicly released in 1994. Way back 
then, the language was free for aeademie use, but commercial licenses had to be 
negotiated. However, no commercial negotiations ever occurred, and in Feb 1995, with 
Version 2.1, the license opened up to commercial use. For the most recent version of 
Lua, check with the Lua horne page at http://www.lua.org . 

Or with Tecgraf at http://www.tecgrafpuc-rio.br/ . 

Lua was designed to run on anything out of the box. This versatility is a resuit of its 
plain vanilla C; you just need an ANSI C compiler to compile it. Lua should run not 
only on all Standard Windows platforms, but also on UNIX, Linux, Solaris, SunOS, 
AIX, ULTRIX, and IRIX, not to mention NextStep, OS/2, Sony Playstation, Macs, 
BeOS, MS-DOS, OS-9, OSX, EPOC, and the PalmOS. Whew! Again, all you need is 
an ANSI C compiler to build Lua on the given platform. 

The Lua Interpreter 

The standalone interpreter (lua.exe on Windows machines) that comes with Lua is 
extremely useful, as it runs an interactive mode. When fired up, the interpreter displays 
the Lua version number and Copyright notice at the top of the window, along with a 
greater than (>) Symbol as a prompt (see Figure 2.14). 

Figure 2.14. Opening the Lua standalone interpreter 



In the interpreter, each command that you type executes immediately after you press the 
Enter key, and that line is considered to be a whole Eua chunk (more on Eua chunks in 
just a bit). The Lua interpreter is fairly smart, and if you need to enter multiple lines (for 
example, when creating a function), the Lua interpreter doesn't execute right away; 
instead, you will see two greater than symbols, indicating that the interpreter is waiting 
for you to end the function before executing (see Eigure 2.15). 

Figure 2.15. The multiple-line function in the Lua interpreter 
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Most of the commands and samples in this chapter can be run in the interpreter, whieh 
is an exeellent tool for getting a feel for Lua. I suggest you keep the interpreter open and 
try the sample code as you go along in the book. 

Creating Lua Program Files 

As I said, Lua is normally implemented via its host language. The host calls Lua with a 
lua_open eommand and then eloses it with a lua_close eommand. A unit of Lua is 
stored in a file or string within the host program and is ealled a ehunk. When the host 
executes a Lua ehunk, the ehunk is preeompiled into byteeode for a virtual maehine, and 
then the statements are exeeuted in a sequential order. This Lua ehunk does its thing, 
perhaps making ehanges to the global environment (that persist after the ehunk ends), 
and then it ends (see Figure 2.16). 

Figure 2.16. Lua beiug implemeuted via the C host iauguage 



NOTE 
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The term virtual machine (VM) was coined by Sun Microsystems to describe the 
runtime environment for their budding Java language. A VM acts as an interface 
between a compiled binary code and an operating system. 

Lua has been designed as an extension language but it can be used as a stand-alone 
language as well. The Lua interpreter (named lua.exe) can be called via command line 
to execute Lua files (known by their .lua extension) and accepts a number of arguments, 
as shown in Table 2.7. 


Table 2.7. Lua Interpreter Command-Line Arguments 


Argument 

Purpose 

- 

Executes stdin as a file 

-e stat 

Executes string stat 

-f file 

Requires file 

-i 

Enters interactive mode after running script 

-V 

Prints the version Information 

— 

Stops handling options 


If the Lua interpreter is given no arguments, it behaves as i f lua oras lua -v -i 
when stdin is a terminal. 

Chunks of Lua can be also precompiled into a binary form with Luac.exe, which is also 
included in the win32 executables. Luac.exe is a Lua bytecode compiler, an assembler 
that compiles the Lua source code into bytecode. This makes it completely unreadable 
to normal humans but also makes it run much faster. To use the bytcode assembler, you 
just call it as if you were compiling and then teli it what you want the new file to be 
(with a .lub extension) and what the sourcefile (.lua) is. 

Luac.exe -o Myfile.lub Myfile.lua 


The -o is one option to feed Luae, which means "output to file." For a full list of Luae 
options, see Table 2.8. 


Table 2.8. Luae Options 


Option Purpose 

Produce a listing of the compiled bytecode for Lua's virtual machine 
-o "file" Output to fde, instead of the default luac.out 
~P Load files but do not generate any output fde 

Perform integrity tests of precompiled chunks 
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Table 2.8. Luae Options 


Option Purpose 

Print version information 


NOTE 

As Lua was written in ANSI C, you need to do special work when embedding Lua into 
a C++ application due to the "name mangling" that C++ performs. You must place 
extern "C" around the inclusion of Lua headers in a C++ application; 

extern "C"{ 

# include "lua.h" 

} 


Lua has no if def cplusplus or if def c directives, because it is pure, clean ANSI C. 
This pureness makes the extern eommand necessary; without it, you will get link 
errors. 

Lua's "Helio World" 

Lua is quite different than the other two languages presented in this book. Lua is 
primarily an extension language, and Lua code is usually embedded within a host. 

You'll find Lua residing inside C, Python, and Ruby Scripts, doing what it does best— 
acting as code within eode. In-depth eoverage of how to program with Lua is covered in 
Seetion 2 of this book, and what follows is just an example to whet one's appetite. With 
the understanding that a Lua "Helio World" program would normally exist within 
another language's construet, writing a "Helio World" program in Lua is even shorter 
and simpler than in Python or C: 


— HELLO_LUA_l.lua 

-- This program displays the string "hello" . 

-- It prints the string by using an internal print eommand. 

print "hello world\n" 


Notiee that Lua's eomments are different; they are marked by two dashes (—) instead of 
a pound (#) sign. Also notiee that the print line itself is almost exaetly like the C version 
Hello C l .epp above, exeept in this case that you do not need to import a library for the 
print eommand, and a few of the symbols, namely the semicolons and parentheses, are 
left out. 

The Ruby Environment 

Ruby is most used to Posix type operating Systems (sueh as UNIX, Linux, and 
LreeBSD) and is written in the C programming language. Although Ruby is eomfortable 
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on UNIX, Linux, DOS, the various Windows flavors, Macintosh, and number of other 
platforms, it's most at horne on the Posix environment where it was bom. 

Ruby on Windows needs a few additional tools in order to emulate its horne 
environment. These tools include a Linux-like environment for Windows called cygwin, 
a collection of Windows header files and libraries called mingw, and the D J Delorie 
Software tools (djgpp). Preeompiled versions of Ruby with these tools included can be 
found at the Ruby Central Website, whieh houses the Ruby "one-eliek" installer for 
Windows at http://www.rubveentral.eom 

The latest versions of this collection of tools can be found at their own respeetive 
Websites as well: 

• cygwin, http://www.cvgwin.com/ . 

• mingw, http://www.mingw.org/ . 

• djgpp, http://www.delorie.com/ . 

This Windows one-click installation is also included on the CD that accompanies this 
book, and can be found in the Ruby folder: \RUBY 

Installing Ruby 

The latest version of Ruby, 1.8.0 as of this writing, can be downloaded firom the Ruby 
language organization Website at http://www.rubv-lang.org . 

Developers can also take a peek at the source tree at that loeation. Ruby Version 1.8.0 is 
also on this book's CD in the \RUBY folder. 

Windows users can simply use the one-eliek installer exeeutable to install Ruby on their 
machines; just double-click on rubyl80-10.exe to run the Ruby Setup Wizard. You may 
have to restart your computer afterwards. 

Steps for installing Ruby on a Posix environment will vary, depending on the platform 
and also on any extension or static module linking that needs to be done. The following 
eondensed steps will suffiee for most folks, however: 

1. Beeome a super user or user with privileges for installing new programs. 

2. Run autoconfto generate configure. 

3. Run . / configure to generate config.h and the makefile. 

4. Run make. 

5. Run make install. 

The Ruby Interpreter 

Ruby ean be used interactively with the interpreter, ealled irb, that eomes bundled with 
it. For UNIX machines you need to add irb/ to the $rubylib environment variable and 
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make a symbolic link to the irb.rb file in your path environment. Then you can type in 
irb to eall the interaetive Ruby shell. 

On Windows, the irb is installed by default in the program fde's direetory, and the Ruby 
shell is aeeessible through the Start menu under Programs (see Figure 2.17). The eode 
samples in this ehapter ean be run with the Interaetive Ruby Shell. 

Figure 2.17. Launching the Ruby interpreter from the Program menu 



A program ealled eval, whieh is ineluded in the samples/direetory of the Ruby 
distribution, allows you to enter expressions and view their values. 

Creating Ruby Program Fiies 

Ruby program files invariably end with an .rb extension. They ean be ereated in 
Notepad or vi or any other sort of text editor. To make things even easier, Ruby eomes 
bundled with a nifty tool for seripting ealled the SeiTE, whieh is a Seintilla-based text 
editor. SeiTE has features for building and running many kinds of programs (see Eigure 
2.18), and it understands the syntax of a smattering of different eomputer languages, 
ineluding Python, Eua, and Ruby. 

Figure 2.18. The SeiTE editor shows offits knowiedge ofRuby syntax. 
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Executing Ruby 

Ruby itself (that is, Ruby.exe) is meant to run on the command line, whether it's the 
UNIX shell or Windows eommand or DOS. The basie syntax for running Ruby is as 
follows: 

Ruby options MyProgramScript arguments 


Being a ehild of the eommand line, Ruby accepts a number of fun eommand-line 
options, or switches; these are outlined in Table 2.9. 

Ruby eomes with a Ruby Windows exeeutable ealled rubyw.exe that will run on a 
Windows environment without launehing a DOS or Windows eommand-line window, 
but the Windows platform will need to have .rb files assoeiated with the exeeutable for 
launehing. 

Ruby is primarily used as an interpreted language or as an extension. One extremely 
eommon use is to find Ruby on a server maehine like a Web server where it is used as 
an interpreted language to run CGI or ereate Web forms and eookies. Ruby ean also be 
embedded into HTML doeuments, another eommon use of the language. 


Table 2.9. Ruby Command-Line Switches 
Argument Purpose 

-Odigit Speeifies the input reeord separator ($/) as an oetal number 

Turns on auto-split mode 

Cheeks the syntax of the seript and then exits without exeeuting 
“Kc Speeifies the KANJI (Japanese eharacter) eode-set 
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Argument 

-d 

--debug 

-e 

-F 

-h 

--help 

-I 

-1 

-n 

-P 

-r 

-s 

-S 

-T 

-V 

--verbose 

--version 

-w 


X[directory] 
-X 

-y 

--yydebug 


Table 2.9. Ruby Command-Line Switches 
Purpose 

Turns on debug mode 
Turns on debug mode 

Used to specify a script from the eommand line 

Used to speeify the input field separator 

Prints a summary of all the eommand options 

Prints a summary of all the eommand options 

Specifies in-place-edit mode 

Enables automatie line-ending proeessing 

Used to run multiple iterations around the given seript (looping) 

Same as -n but prints the value of variable $_ at eaeh end of the loop 
Causes Ruby to load a given fde using require 
Enables some switeh parsing for switehes 

Eorces Ruby to use the path environment variable to seareh for seript 
Eorees taint type eheeks to be turned on at the given level 
Enables verbose mode 
Enables verbose mode 
Prints the Ruby version 

Enables verbose mode without printing the version message at the 
beginning 

Telis Ruby that the seript is embedded in a message and switehes to a 
given directory (if provided) before executing a script 

Causes Ruby to switeh to a given directory 

Turns on compiler debug mode 

Turns on compiler debug mode 


The most common use for games is to have Ruby associated with C as an extension. 
The Ruby interpreter is embeddable, and it is possible to embed the entire Ruby 
interpreter into C or other code. Just like Eua, Ruby has a full C API, which TU cover in 
Chapter 10, and it is extendable not only with C but with other languages; TU discuss 
doing that in Chapter 12. 

Ruby's ”Hello World” 

A "Helio World" program in Ruby looks a lot like Python's: 


#!/usr/bin/ruby 
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############ 

# HELL0_RUBY_1.ruby 

# This program displays the string 

# It first shows the path to ruby, 
############ 

puts "Helio!" 


"hello" . 

and then prints 


the 


string. 


Ruby's code is extremely streamlined in this example. A built-in puts command 
handles the printing without the need of any loops, spacing, brackets, or semi-colons. 
Very elean, this seript simply telis the computer where Ruby is and then, in one line, 
telis it what to do. 
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Summary 

IVe covered quite a bit in this short chapter. Before you move on to more specifics with 
Python in the next ehapter, or the other languages later on, you'll want to be sure you are 
familiar with Boolean logic and general program flow and strueture with eonditional 
and iterative eontrol eonstruets. Important points from this chapter: 

• Python, Lua, and Ruby organizations keep active lists of projects that are pretty 
extensive. 

• Math and algebra are handled very similarly in each language. 

• Boolean operators, Boolean comparisons, eonditional eontrol statements, and 
iterative eontrol statements can all be used to eontrol the flow of a program. 

• Lists, strings, and a number of other commands all look and are handled in a 
similar way in each language. 

• Implementing "Helio World" in a Standard way in C takes more lines of code 
and more symbols than any of the other three languages. 
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Questions and Answers 


1: Q: Why are there more projects in Python and Lua than Ruby? 

A: A: Ruby is probably the most diffieult of the three languages to find evidenee 
of in the game industry. This is partly due to the language barrier (again, most 
modern Ruby development is in Japanese) and also because shops today tend 
to be using Ruby more for projects with the World Wide Web, XML 
integration, text processing, and general scripting. That doesn't mean Ruby 
isn't suited for game development; quite the contrary, as you will shortly see. 

2: Q: I already know how to program "Helio World", when do I get to write 
graphio s and games? 

A: A: You'll start writing much more in-depth code in the very next chapter. 
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Exercises 


1: Describe the difference between a conditional control statement and an 
iterative control statement. 

2: Boolean logic uses only two values. Which two values are they? 

3: Which e ise/if structure (elseif, elsif, and elif) gocs with which 
language (Python, Lua, and Ruby)? 

4: When printing a simple statement (like "Helio World"), one of the three 
languages normally uses a puts command instead of a print command. 
Which one is it? 
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Part TWO: Programming with Python 


The next three chapters are all about Python. This part of the book starts with an 
OverView of the Python language and its syntax, then moves in to examine eommonly 
used libraries for writing games in Python, ineluding Pygame and PyOpenGL. Finally, a 
few real-world Python game projects are examined. 
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Chapter 3. Getting Started with Python 

Latet anguis in herba 

-Virgil (70-19 BC), Roman poet, "Aeneid" (Translation: There's a snake hidden in 

the grass.) 

Let's jump right into programming with Python. FU start with an introduction to a few 
useful tools and then give you a speedy overview of the Python language. 
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Python Executables 

You can execute .py files once Python is installed on your machine, but that doesn't 
make your Python game programs universally playable. You stili need to convert your 
Scripts into a bundled executable for whatever platform you want to run on. Luckily, 
there are a few resources for accomplishing just that. 

Packaging Python Code 

When modules are imported in Python by other modules, Python compiles the relevant 
code into byte-code, an intermediate, portable, closer-to-low-level binary language 
form. This byte-code is stored with the .pyc suffix, short for Python compiled, instead 
of the typical .py. 

Python's .pyc files correspond roughly to DLLs (dynamically loaded libraries) used in 
C. Regular .py modules can be used dynamically, too, but the compiled Python code is 
tighter and Python interprets the code at runtime when the file is imported. 

Precompiling Scripts is one way to speed up Python programs that need to import many 
modules. You can minimize a program's startup time by making sure source code is 
kept in directories where Python will have access to writing .pyc files. 

You can also ship Python programs as .pyc files rather than as .py Scripts. Since .pyc 
files are binary, they cannot be run as Scripts, but they can be sent to the Python 
interpreter; simply add the name of the .pyc file the next time you run Python, like this: 

Python runme.pyc 


In order to build a compiled Python file from the Python interpreter, import the compile 
function from py compile and run the compile command, like this: 


from py compile import compile 
compile("script to compile.py") 


Freeze 

Freeze is a system that takes Python script files and tums them into modules packaged 
into C files. Originally Freeze was used as one way to ship Python source, but it is now 
mostly defunct, although it will stili be available in Version 2.3 for backwards- 
compatibility. The compiled script that Freeze generates allows a Python program to 
ship without the source code in plain view and without using .pyc fides. The benefits to 
Freeze are that you can ship Python as two .c files and a makefile instead of as a .py, 
and you can make Python runable on platforms that do not have Python installed. The 
downside is that Freeze doesn't work well initially with Tkinter and other Windows 
GUIs. 
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ActiveState 


ActiveState is a company that focuses on applied open source. It creates development 
packages for Software developers and provides resources for Perl, Python, and PHP 
development. ActiveState currently has a Python distribution called ActivePython. It 
also supports creating Python RPM (Red Hat Package Managers) installers, Windows 
complete installers, and a Visual Studio .NET IDE plug-in for Python. These Services 
(some are firee, others not) are available at the ActiveState Python Website, at 
http://www.activestate.com/Solutions/Programmer/Pvthon.plex . 

pylexe 

The py2exe extension is an open source utility that converts Python Scripts into 
executable Windows programs. The Software is copyrighted by Thomas Heller but is 
freely distributable, and you'll find a copy with the license on the accompanying CD 
under Python/py2exe. 

The extension is stili under development but has expanded recently to include the ability 
to tum Python Scripts into Windows NT-like Services; it has been used to create a 
number of popular Python applications, such as wxPython, Tkinter, and pygame (you'll 
get to know these applications a bit better in the next chapter). 

py2exe is a Distutils (Python Distribution Utilities) extension, and relies on the work by 
Greg Ward to make Python programs distributable (see the Disutils Website at 
http://www.pvthon.org/doc/current/dist/) . The Distutils are necessary for py2exe to 
work and are also included on the Python folder in this book's CD. 
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Python Debuggers 


Python comes with a built-in pdb (Python Debugger) module that defines an Interactive 
souree eode debugger for Python programs. The Python debugger supports a number of 
useful programming funetions, sueh as breakpoint setting, staek frame inspeetion, 
souree eode listing, and so on, but unfortunately the debugger has been (historieally) 
poorly doeumented and the windowing version module (wdb) is eonsidered a bit 
primitive. 

Sinee souree-level debugging is sueh an important part of programming, a few 
improvements have been made to the existing Python debugger. Two popular free 
Python debuggers are commonly used. The first is PythonWin, the Python for Windows 
extension. Unfortunately it only runs on Windows. The seeond is the HAP (Humongous 
Addition to Python) debugger developed at Humongous. 

PythonWin 

PythonWin is a Python debugger and an IDE that runs on Windows. Versions for 
Python 2.2 and 2.3 are included on the aceompanying CD under Python/debuggers. 
PythonWin is beeoming the Standard Windows debugger and is now ineluded in some 
distributions of Python (for instanee, in AotiveState's AetivePython). PythonWin has a 
GUI environment (see Figure 3.1) but ean also be run via command line. 

Figure 3.1. Opening shot of the Python Win debugger 



PythonWin is basieally a wrapper for the MFC (Mierosoft Foundation Class) libraries. 
PythonWin is copyrighted by Mark Hammond but is freely usable and distributable as 
long as the lieense (found in both the Fieenses folder and the 
Python/Debuggers/PythonWin folder on the CD) aeeompanies the binary. 
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The Open Source HAP Debugger 

HAP can be found among other open-source Sourceforge projects 
(http://hapdebugger.sourceforge.net/) and is released under the Gnu Lesser General 
Public Licenses (you can read the license in detail on the CD in the Licenses folder). 

The HAP debugger can be run remotely, which makes it an ideal tester for a computer 
game in a lab environment. The game can run on full screen on one machine while a 
second machine can debug it remotely. 

The HAP debugger Version 3.0 is included on the CD, under the 
Python/debuggers/HAP folder. HAP was built with the idea that the debugger would 
move to console game development and development on the Macintosh, but currently it 
runs only on Windows 2000 and must be built with Visual C++. It provides a few 
features the Standard Python debugger cannot, such as a full-screen mode and multi- 
threading. The debugger has two applications. The first is the editor and IDE, and the 
second is the remote debugging host. The first application runs whatever Python script 
is being debugged and then communicates to the IDE via a network socket. 

NOTE 

Consoles don't have keyboards, mice, or multiple monitors, so the default Python 
debugger isn't so great when you need to test console type games written in Python. 

This is one of the reasons Humongous developed the HAP debugger: remote debugging 
frees you firom the platform and allows you to debug in a comfy computer environment. 

NOTE 

One Game Script's History 

Before Humongous Entertainment used Python, they had an internal tool named 
SCUMM (Script Creation Utility for Maniae Mansion). Maniae Mansion was a project 
originally under EucasEilm Games, and SCUMM was the custom scripting language 
and game engine used to develop Maniae Mansion. 

SCUMM was created by Aric Wilmunder and Ron Gilbert when they worked for 
EucasEilm. When Gilbert later founded Humongous and Cavedog Entertainment in the 
Pacific Northwest, he brought with him SCUMM, which the new companies used to 
create over 50 different games, including Humongous's original popular Ereddi Eish, 
Putt Putt, and Pajama Sam children's tities. 

SCUMM's limitations became too restricting after a decade or so of use, and at that time 
the company switched over to using C++ and Python for game development. The first 
game it scripted with Python was Backyard Hockey. The Game Logic, AI, menu, and 
actual executable of Backyard Hockey were ali Python, which called in C++ modules 
for heavy graphics and sound when necessary. 
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Python Language Structure 

Now that you can install and run Python in a variety of ways, it's time to get a real 
handle on the language itself. This seetion goes over Python's types, earries on from last 
ehaptePs seetion on math and loops, and also introduees a few new eoneepts. 

Python Punctuation 

As you have seen from the previous Helio World! examples, Python doesn't need a lot 
of punetuation. In partieular, Python doesn't use the semieolon (;) to mark the end of 
line. Unlike C, Perl, or a number of other languages, the end of a line is aetually marked 
with a newline, so the following is a eomplete eommand in Python: 


print "hello" 


Code bloeks are indieated in Python by indentation following a statement ending in a 
eolon, for example: 


if name == this is true: 

# run this block of code 
else: 

# run this block of code 


Getting used to white spaee that aetually means something is probably the most diffieult 
hurdle to get over when switehing to Python from another language. 

NOTE 

CAUTION 

UNIX, Windows, and the Macintosh Operating System all have different conventions 
for how to terminate lines in text files. This is an unfortunate feature of multi-platform 
programming, and since Python uses terminated lines as syntax, your Python Scripts 
written in text editors may not work on different platforms. The Macintosh version of 
Python recently fixed this problem; it now checks line endings when it opens a file and 
adjusts them on a per-file basis. It may be possible to find or write a filter that 
substitutes end-of-line characters for different platforms. Compiling Scripts to byte-code 
before platform-hopping is another possible workaround. 

Lauguage Types 

Python includes a handful of built-in data types (see Table 3.1); the most commonly 
used of these data types are numbers, strings, lists, dictionaries, and tuples. Numbers are 
fairly obvious, although there are several different number types, depending upon the 
complexity and length of the number that needs to be stored. Strings are simply rows of 
letters. Lists are groups that are usually comprised of numbers or letters. Dictionaries 
and tuples are advanced variable types that are similar to lists and comparable to arrays 
in other languages. These types all have built-in operations, and some have built-in 
modules or methods for handling them. 
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Table 3.1. Built-In Python Data Types 


Name 

Data Held 

complex 

Complex numbers (see Table 3.2) 

dict 

Dietionary 

file 

File 

f loat 

Floating point number (see Table 3.2) 

hexadeeimal(Ox) 

Hexadeeimal number 

int 

Integer (see Table 3.2) 

list 

List 

long 

Long integer (see Table 3.2) 

obj ect 

Base objeet 

octal(0) 

Oetal number (see Table 3.2) 

str 

String 

tuple 

Tuple 

Unicode 

Unieode string 


Numbers 

Python has several basic numeric types; they are listed in Table 3.2. 


Table 3.2. Python Basic Numeric Types 


Type 

Example 

integer 

1 

long integer 

lllllllL 

floating point 

1.1 

complex 

l.lj, .1 

octal 

0111 

hexadeeimal 

0x1101 


Integers are the most eommonly used math eonstruet and are eomparable to C's long 
integer. Long integers are size-unlimited integers and are marked by an ending L. 
Floating points are integers that need a floating deeimal point and are equivalent to C' 
double type. Oetal numbers always start with a 0, and hexadeeimal integers always 
begin with a Ox in Python. 

Numbers ean be assigned just like you would in a high sehool algebra math problem: 



X = 5 


The basic math operators *, /, **, %, and so on), which were listed in Chapter 2, 
can be used in the Standard mathematical sense. 


# 

Make 

X equal 

to 

2 

times 6 

X 

= (2 

*6) 




# 

Make 

y equal 

to 

2 

to the power of 6 

y 

= (2 

** 6) 





Print y 


Python always rounds down when working with integers, so you if you divide 1 by 20 
you will always get 0 unless you use floating point values. To ehange over to floating 
point math, simply plaee the decimal in one of the equation's numbers somewhere, like 
so: 

# This will equal 0 
X = (1/20) 

print X 

# This will get you a floating point 
y = (1.0/20) 

print y 


In addition to your basio math operators, oomparison operators (>, <, !=, ==, =, >=, and 
<=) and logioal operators (and, or, not) oan be used with basio math in Python. These 
operators oan also oompare strings and lists. 

NOTE 

The trunoation, or "rounding down," during integer division is one of the more oommon 
stumbling blooks for new users to Python. 

Python oomes with a built-in math module that performs most of the oomplex constant 
functions. The more common constants are listed in Table 3.3. 


Table 3.3. Common Functions from ma th 


Function/Constant Description 

pi The mathematical constant approximately equal to 3.14 

e The base of the natural logarithm (In) approximate ly equal to 2.7 

f irid Finds the lowest index where the second string (argument) appears 

in the first 


Python also has a built-in random module just for dealing with random numbers. A few 
of the more common random functions are listed in Table 3.4. 
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Table 3.4. Common random Functions 


Function 

seed 
random 
randint 
uniform 
choice 


Description 

Seeds the random number generator; default seed is the current time 
Retums the next random number as a floating-point number between 0 and 1. 
Retums a random number between two given integers 
Retums a random number between two given floating-point numbers 
Randomly chooses an element from the specified list or tuple 


Strings 

You designate strings in Python by placing them within quotes (both single and double 
quotes are allowed): 

Print "hello" 'hello' 


Strings store, obviously, strings of characters. Occasionally you will want to print a 
special character, like a quote, and Python accepts the traditional backslash as an escape 
character. The following line: 

Print "\"hello\"" 


prints the word hello in quotes. A few other uses of the escape sequence are illustrated 
in Table 3.5. 


Sequence 

Table 3.5. Python Escape Sequences 

Function 

\n 

Prints a newline 

\t 

Horizontal tab 

\b 

Deletes the last character typed 

\a 

System beep 

W 

Prints a backslash 

\r 

Prints a carriage return 


Like with variables, you can manipulate strings with operators. For instance, you can 
concatenate strings with the + operator: 

# This will print mykonos all together 
print 'my'+'konos' 
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Anything you enter with print automatically has a newline, \n, appended to it. If you 
don't want a newline appended, then simply add a eomma to the end of the line with 
your print statement (this only works in non-interaetive mode): 


# These three print statements will all print on one line 
print "I just want to fly", 
print "like a fly", 
print "in the sky" 


Lists 

Lists were introdueed in the Chapter 1. In Python, lists are simply groups that can be 
refereneed in order by number. You set up a list within braekets [] initially. Integer- 
indexed arrays start at 0. The following eode snippet ereates a list with two entries, 
entry 0 being "Ford", and entry 1 being "Chrysler", and then prints entry 0: 

cars = ["Ford", "Chrysler"] 
print cars[0] 


In Python, there are a number of intrinsie functions, or methods, that allow the user to 
perform operations on the objeet for whieh they are defined. Common list methods are 
listed in Table 3.6. 


Table 3.6. Common List Methods in Python 


Operation 

list = range () 
list.append() 

list.insert(index, element) 

list.sort () 

dei list [: ] 

list.reverse () 

list.count () 

list.extend(list2) 

list.remove() 


What it does 

Creates a list 

Adds an element to the end of the list 
Inserts an element at index 
Sorts the list 

Deletes a sliee or seetion of a list 
Reverses the list 

Retums the number of elements in list 
Inserts iist2 at the end of list 
Removes an element firom the list 


So, for instanee, you ean add to the list simply by using the append method: 

cars.append ("Toyota") 
print cars 


87 



Or you can slice up lists by using a colon. Say you want to print just the first through 
the second item from the cars list. Just do the following: 

print cars[0:2] 


Lists ean eontain any number of other variables, even strings and numbers, in the same 
list, but eannot eontain tuples or nested lists. Onee ereated, lists ean be aeeessed by 
name, and any entry in a list can be aeeessed with its variable number. You ean also 
referenee the last item in a list by using -l as its referenee number. 

# This line prints the last entry in the cars list: 
print cars[-1] 


You ean also use the basie operators explained in Chapter 2 to perform logio on lists. 
Say you need to print the cars list twice. Just do this: 

print cars+cars 


Lists ean also be oompared. In a oase like this: 

[1, 2, 3, 4] > [1, 2, 3, 5] 


the first values of eaoh list are oompared. If they are equal, the next two values are 
oompared. If those two are equal, the next values are oompared. This oontinues until the 
value in one is not equal to the value in the other; if all of the items in eaoh list are 
equal, then the lists are equal. 

NOTE 

CAUTION 

Charaoters in a string aot just like elements in a list, and ean be manipulated in many of 
the same ways, but you eannot replaoe individual elements in a Python string like you 
ean with a list. 

If you need to iterate over a sequence of numbers, the built-in funotion range () is 
extremely useful. It generatos lists oontaining arithmetio progressions, for instance: 


# This snippet assigns the numbers 0 through 9 to listi and then 
prints the, 
listl=range(10) 
print listi 


It is possible to let range start at another number, or to speoify a different inorement: 

# The following line assigns the numbers 5-9 to list2 
list2=range(5, 10) 
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print list2 

# The following line creates a list that jumps by 5s from 0 through 50 
and assigns it to 

list3 

list3=range(0, 50, 5) 
print list3 

# The following line does the same only in negative numbers 
list4=range(-0, -50, -5) 

print list4 


Tuples 

Python also has a structure called a tuple. Tuples are similar to lists and are treated 
similarly, exeept that they are designated by parentheses instead of braekets: 

tuplel = ( a, b, c) 


You don't aetually need parentheses to ereate a tuple, but it is eonsidered thoughtful to 
inelude them: 

tuplel = a, b, c 

You ean ereate an empty tuple by not ineluding anything in parentheses: 

tuplel = 0 

There is also a version of the tuple, ealled a singleton, that only has one value: 

Singletonl = a. 


While lists normally hold sequenees of similar data, tuples (by eonvention) are normally 
used to holds sequenees of Information that aren't neeessarily similar. For example, 
while a list may be used to hold a series of numbers, a tuple would hold all of the data 
on a partieular student—name, address, phone number, student ID, and so on—all in 
one sequenee. 

So what makes tuples so speeial and different? Well, for one thing, tuples ean be nested 
in one another: 


tuplel=(1,2,3) 
tuple2=(4, 5, 6) 
tuple3 = tuplel, tuple2 
print tuple3 


When you enter the last line and print out tuple3, the output is: 

( (1, 2, 3) , (4, 5, 6)) . 
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NOTE 


TIP 

For convenience, there is tuple () function that converts any old list into a tuple. You 
can also perform the opposite operation, using the list () function to convert a tuple to 
a list. 

You can see how Python continues to bracket and organize the tuples together. Nesting 
tuples together in this way, also called packing, can provide a substitute for things like 
two-dimensional arrays in C. 

There is one more interesting feature, called multiple assignments, in tuples. 

X, Y = 0, 1 


Python assigns X and Y different values, but on the same line of code. Multiple 
assignments can be very useful and quite a timesaver. 

Dictionaries 

Python has a third structure that is also similar to a list; these are called dictionaries and 
are indexed by assigned keys instead of automatic numeric list. Often called associative 
arrays or hashes in other languages, dictionaries are created in Python in much the same 
way as lists, except that they are used to create indexes that can be referenced by 
corresponding keys. An example of this might be a phone directory, where each 
telephone number (value) can be referenced by a person's name (key). 

Dictionaries are designated with curly braces instead of brackets. The keys used to 
index the items within a dictionary are usually tuples, so you will see them put together 
often. You can create an empty directory in the same way you create empty tuples, 
except that you replace the parentheses with curly braces, like so: 

dictionaryl = {} 


You assign keys and values into a dictionary using colons and comas, like so: 

key : value, key : value, key : value 

So for instance, in the phone number directory example: 

directory = {"Joe" : 5551212, "Leslie" : 5552316, "Brenda" : 5559899} 
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Then you can access specific indexes by placing the key into brackets. If I wanted to 
reference Brenda's phone number later on, the following snippet would do the job and 
give me 5559899; 

directory [Brenda] 


If I had mistyped the number, I eould ehange it to new value like this: 

directory[Brenda] = 5558872 


Dietionaries have a number of Standard methods assoeiated with them; these are listed 
in Table 3.7. 


Table 3.7. Common Dictionary Methods in Python 

Operation What it does 

ciear {) Deletes all items in a dictionary 

get () Returns key value 

has_key () Returns 1 if key is in dictionary, else 0 

() Returns a list of keys firom dictionary 

update (dictionary2 ) Overrides the dictionary with values firom dictionary 2, adds 


values() 


any new keys 
Returns a list of values 


Identifiers 

Identifiers are used in Python to name variables, methods, functions, or modules. 
Identifiers must start with a non-numeric character, and they are case sensitive, but they 
can contain letters, numbers, and underscores (_). 

There are also a handful of words Python reserves for other commands. These are listed 
below: 


and 

elif 

else 

except 

exec 
finally 
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for 


f rom 

global 

if 

import 

in 

is 

lambda 

not 

orassert 

passbreak 

printclass 

raisecontinue 

returndef 

trydel 

while 


As a convention (but not necessarily a rule), identifiers that begin with two underscores 

(_) have special meanings or are used as built-in symbols. For instance, the_ init_ 

identifier is designated for startup commands. 

Python's variables are loosely typed, and you ean assign any type of data to a single 
variable. So, you ean assign the variable x a numerie value, and then turn around later in 
the same program and assign it a string: 


X=lll 
Print X 
X="Mythmaker" 
Print X 


NOTE 

Not realizing that Python's variable names are ease-sensitive seems to be one of the 
most eommon mistakes new users to the language suffer from. 
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Control Structures 


The very common if, elif , and else statements showed up in Chapter 2. These are 
used in Python to eontrol program flow and make deeisions: 

if X ==1: 

print "odd" 
elif X == 2: 

print "even" 

else: 

print "Unknown" 


if ean also be used with Boolean expressions and eomparison operators to eontrol 
whieh bloeks of eode exeeute. Unlike with most other languages, you'll see that 
parentheses aren't eommonly used to separate bloeks in Python, but eolons, tabs, and 
newlines are. 

if 1 >2 : 

print "One is greater than two" 

else : 

print "One is not greater than two" 


Loops 

You saw how Python's for loop is used in Chapter 2. for is fairly versatile, and works 
with lists, tuples, and dietionaries. 


for X in cars: 
print X 


The following example uses f or to loop through the numbers 0-9 and then print them: 

for X in range(0, 10) : 

print X 


This same example ean be rewritten with a while loop: 

X = 0 

while X <= 10 : 

print str(x) 

X += 1 


The else elause will not fire if the loop is exited via a break statement. 


A number of eonvenient shortcuts exist for use with Python for loops; you'll get used to 
using them after a while. For instance, Python will run through eaeh item in a string or 
list and assign it to a variable with very little neeessary syntax: 
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for X in "Helio": 

# In two lines you can print out each item of a string 
print X 


You can use a few borrowed C statements in for and whlle loops in order to control 
iterations, including the break statement, which breaks out of the current for or whlle 
loop, and the continue statement, which jumps to the next iteration of a loop. You can 
also add to the loop an else clause that will execute after the loop is finished (in the 
case of for loops) or when the whlle condition becomes false (in the case of whlle 
loops). 

X = 0 

whlle X <= 10 : 

if X == 22: 

# this breaks out of this whlle loop 
break 

print str(x) 
if X <=11: 

# this jumps to the next loop Iteration 
continue 

X += 1 
else: 

# This happens when x <=10 becomes false 
break 


NOTE 

CAUTION 

If s a common mistake, when first playing with loops, to create a never-ending loop that 
locks out any program control. For instance, the following code will never encounter a 
condition to exit and will therefore execute forever: 

whlle 1 == 1: 

print "Endless loop." 


Modules 

Python is based on modules. What this means is that when a Python source file needs a 
function that is in another source file, it can simply import the function. This leads to a 
style of development wherein useful functions are gathered together and grouped in files 
(called modules) and then imported and used as needed. For instance, lef s say the 
source file MyFile.py has a useful function called Usefull. If you want to use the 
Usefull function in another script, you just use an import command and then call the 
function, like so: 

import MyFile 
MyFile.Usefull () 


94 



For instance, create a file called TempModule.py with the following four lines: 


def one(a) : 

print "Helio" 
def two(c): 

print "World" 


This file defines two funetions: the first funetion prints "Helio" and the seeond one 
prints "World". To use the two funetions, import the module into another program by 
using the import eommand, and then simply call them, like so: 

import TempModule.py 
TempModule.one(1) 

TempModule.two(1) 


The (1) is included here because eaeh funetion must take in one argument. 

You can also use dir () to print out the funetions of an imported module. These will 
inelude whatever has been added and also a few built-in ones (namely_ doc_, 

file , name , and built-ins ). 

Module-based programming becomes particularly useful in game programming. Lef s 
say you like the Usefull funetion, but it really hinders performance when it runs in a 
game beeause it makes a lot of intense graphical ealls or does a lot of complex math. 
You can fix Usefull by simply rewriting the necessary funetions and typing in 
MyFile.py as C++ code (or another language like assembly) and then registering the 
funetions with the same module name. The original Python script doesn't even have to 
ehange; it just now ealls the new, updated, faster C++ eode. Modules make it possible to 
prototype the entire game in Python first and then recode bits and pieces in other, more 
speeialized programming languages. 

Python has a large selection of modules built into the default distribution, and a few of 
the commonly used ones are listed in Table 3.8. 


Table 3.8. Commonly Used Built-In Modules 
Module Description 

sys Basic system and program funetions 

argv List of commands to be passed to the interpreter 

stdout, stdin, and stderr Basic Standard output, Standard input, and Standard error 

Exits the program graeefully 
The paths Python looks at to find modules to import 


exit 

path 
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Libraries 


Python ships with a number of great, well-documented libraries. Some of these libraries 
are providers of Python's mueh-celebrated flexibility. The library list is constantly 
growing, so you may want to check out the Python library reference below before 
embarking on any major projects: 

http://www.pvthon.org/doe/eurrent/lib/lib.html 
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Creating a Simple User Interface in Python 

There are two simple functions in Python for getting keyboard input from the user; 
raw_input and input. The raw_input funetion is the easier to use of the two. It takes 
one argument and waits at a normal keyboard prompt for a user to type something. 
Whatever is typed is then returned as a string: 

X = raw input( "Enter your name: " ) 
print X 


input Works just like raw_input exoept that it is preferable to use with numbers 
because Python interprets the variables as whatever is typed in, instead of eonverting 
any numbers into strings. 

X=input("Enter a Number: ") 
print X 


input will think that everything that has been entered is some sort of number, so if you 
enter in a string by using input, Python will conelude that the string represents a 
number. 

Lef s try input with something a bit more eomplex—a bit of eode that ealculates the 
area of a reetangle. To do so, you simply need two input lines and then a print 
statement that displays the results: 


# This program ealculates the area of a reetangle 
print "Reetangle Program 1" 

length = input("Please put in the length of the reetangle:") 
width = input("Please put in the width of the reetangle:") 
print "Area",length*width 


You ean find this program, ealled Reetangle Program l, in the Chapter 3 folder on the 
CD. When you run it, it spits out output similar to you ean see in Figure 3.2. 

Figure 3.2. Python ealculates the area of a reetangle based on user Input 
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Here is a while loop in action with input: 

# This program adds until the user quits 
a = 1 
sum = 0 

print "Enter Numbers to add:" 
print "Enter Q to quit." 
while a != 0: 

print 'Current Sum:',sum 
a = input('Number? ') 
sum = sum + a 
print 'Total Sum =',sum 


This loop takes in numbers from a user and keeps adding them until the user quits with 
a Q entry. You'll see there is nothing new here; you're just mixing two functions from 
the chapter together. You ean also find this code sample on the CD as Addition i .py. 
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A Simple GUI with Tkinter 


The GUI API approved by Python is a nifty toolkit already familiar to folks in UNIX 
land, TCL (short for Tool Command Language). Tkinker is the library behind common 
Python window interfaces and its version of TCL. Folks familiar with TCL\Tk in UNIX 
will find that Tkinter is very familiar. Although the library gets more extensive 
eoverage in Chapter 4, TU give you a small taste of a GUI that will run on a Standard 
Windows environment to whet your appetite. 

NOTE 

Other GUI paekages besides Tkinter are available for use with Python. For instanee, the 
C STDWIN paekage is somewhat popular. However, Tkinker is the Standard and eomes 
shipped and installed with eaeh Python paekage, so if s generally the first graphieal tool 
folks diseovering Python learn to use. 

GUIs in Python are built firom GUI eomponents. In Windows, these eomponents are 
ealled Windows Gadgets, or widgets for short. These widgets are listed in Table 3.9. 


Table 3.9. Tkinter Widget Components 


Component 

Function 

Button 

Creates a button that triggers an event when elieked 

Canvas 

Displays text or images 

Checkbutton 

Creates a Boolean eheek button 

Entry 

Creates a line that aeeepts keyboard input 

Frame 

Creates the outlying window's edge 

Label 

Displays text as labeis for eomponents 

Listbox 

Creates a list of options 

Menu 

Creates a multiple-seleetion display 

Menubutton 

Creates a pop-up or pull-down style menu 

Radiobutton 

Creates a single option button 

Scale 

Creates a slider that ean choose from a range 

Scrollbar 

Creates a serollbar for other eomponents 

Text 

Creates a multiple line box that aeeepts user input 


When using Tkinter, you start by importing the library and then ereating a firame that 
houses all of the other eomponents: 

From Tkinter import* 
window = FrameO 
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If you run this via a script, or from Python's Interactive mode, you will see an empty 
Tkinter window box appear, as shown in Figure 3.3. 

Figure 3.3. Tkinter produces an empty frame widget 




Let's add a simple label and a quit button to the widget. You will not be able to run this 
code in an interactive environment; you will have to actually create a file with a .py 
extension and run it via command line, DOS prompt, or by double-clicking it. For 
reference, the completed script can be found in the Chapter 3 folder on the CD. 

To add a label, you need to first add the pack method. The pack method is used to 
determine the size and influence of a given component: 


window.pack() 


After referencing the pack method, you can add the Label method and specify the text 
(' Helio ') and placement (top) inside parentheses: 


Label(window, text='Helio').pack(side=TOP) 


Finally, you add a button using the Button method, specifying the text (' Exit '), the 
command the button will execute (. quit), and then you teli the pack method where to 
place the button (bottom): 


Button(window, text='Exit', cominand=window.quit).pack(side=BOTTOM) 


One last step is to use the mainioop method to start the event loop. The full code snip 
follows and produces something similar to that in Figure 3.4: 
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Figure 3.4. Tkinter says "Helio " with a slightly more complex wldget 



from Tkinter import * 
window = Frame() 
window.pack() 

Label(window, text='Helio').pack(side=TOP) 

Button(window, text='Exit', cominand=window.quit).pack(side=BOTTOM) 
window.mainloop() 


To create a simple user interfaee utilizing Tkinter, you will need to take advantage of 
Tkinter's Entry eomponent. Entry works just like raw_input and will take what a user 
types in and return it after the Enter key is pressed. A simple Entry box ean, by adding a 
line to Tkinter_Heiio, specify a name for the widget and teli pack how to display it. 
Adding this line above the mainloop () eommand in Tkinter_Hello will give you an 
entry in the window you ereated to type into, as shown in Eigure 3.5 (this eode sample 
is also On the CD as Tkinter Hello_2 .py). 

Figure 3.5. Now the Tkinter wldget also has an entry box for typlng Into 



Entry(name = "texti").pack(expand = YES, fili = BOTH) 
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Memory, Performance, and Speed 

In Python, everything is an object, and all objects are allocated in dynamic memory 
(also called the heap). Because all objects are reference counted, you don't have to 
worry about freeing memory yourself; this is one of the great benefits of a high-level 
language. But if you're writing a game, especially a game that has to operate on a PDA 
or console, you may have to worry about memory allocation and memory fragments. 

The Garbage Collector 

The first issue is garbage collection. Traditionally, a game's biggest problem is with 
memory locks that get used up by the game process but not released back to the 
computer—that is, memory leaks. When a variable goes out of scope or is deleted, it 
needs to move toward being freed from memory. Problems can arise, however, if a 
variable is referencing a number of objects—these extraneous objects may keep the 
variable from being deleted. The worst-case scenario is when object A is referencing 
object B and vice versa, in which case neither object can be deleted. Since Python 
automatically reference-counts each object, this isn't a giant problem. Python's garbage 
collector will sweep through all objects eventually and clean them up. However, 
Python's collector will not automatically pick up references to unwanted objects or 
unclosed fdes. Failure to delete references to unused objects and leaving unused fdes 
open could cause memory leaks to occur. As a rule, all resources in a program should be 
released as soon as they are no longer needed. 

Another potential problem with automatic garbage collection is that as a programmer, 
you have zero control over when the collector runs. If the collector decides to run while 
an important level-loading movies sequence is occurring, or during an unusually intense 
graphic sequence, your game could lose flow or its frame rate could be lowered. One 
solution to this is to temporarily disable Python's garbage collector while the game is 
running and then explicitly call it when you want it. 

Access Python's garbage collector with the gc (short for Garbage Collection) module. 
Python's garbage collector is capable of reporting on how many unreachable objects are 
stili allocated memory (this feature is called the Cycle Detector) or how many objects it 
is currently tracking. These methods (and others) are listed in Table 3.10. 


Table 3.10. Commonly Used gc Functions 


Function 

Purpose 

collect () 

Does a full memory collection 

disable() 

Turns automatic garbage collection off 

get debug() 

Gets debug flags 

get objects 

Returns a list of the objects the collector is tracking 

get referrers 

Returns a list of objects that refer to other objects 

get threshold 

Returns current collection threshold 

garbage 

Where Python places cyclic garbage with finalizers 
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Function 

enable () 
isenabled() 
set_debug() 
set threshold 


Table 3.10. Commonly Used gc Functions 
Purpose 

Turns automatic garbage collection on 

Returns true if automatic garbage collection is on 

Sets debug flags 

Sets the collection threshold 


Several constants are also provided for use with set_debug (), as shown in Table 3.11. 


Constant 

DEBUG_STATS 

DEBUG_COLLECTABLE 

DEBUG_UNCOLLECTABLE 

DEBUG_INSTANCES 

DEBUG_OBJECTS 

DEBUG_SAVEALL 

DEBUG LEAR 


Table 3.11. set_debug Constants 
Use 

Print statistics during collection 

Print information on any collectable objects found 

Print information of any uncollectable objects found 

Print information about instance objects found 

Print information about objects other than instance objeets 
found 

When this flag is set, all unreaehable objects found will be 
appended to garbage rather than being freed 

Print information about a leaking program 


You can use the dei command to forcibly remove an objeet firom memory. However, 
dei is a finalizer; if you use it on an objeet, the garbage colleetor can no longer play 
with that objeet, and it loses control. So be sure you know what you are doing. 

NOTE 

CAUTION 

Python's cyclie garbage colleetor is new as of Python 2.0, and the gc API was added in 
Version 2.2. Earlier versions of Python will not be as pliable where garbage collection 
is concemed. 

NOTE 

TIP 

The stack dealloc function is what Python uses as a destruetor to clean up memory 
blocks after they have been designated. This frees up the memory in PyMem_DEL, the 
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space that holds objects that are decrementing toward deletion. However, if you aren't 
familiar with C style malloc type eommands or memory management on a base level, 
you should probably hold off on forcibly elearing memory. 

Pool Allocators 

Another eoneern, partieularly with consoles, is keeping Python memory allocation 
contained. Using memory or the garbage collector carelessly can cause Python to swoop 
in and eat up all a machine's available virtual memory. The trick is to isolate Python into 
its own memory arena. 

Luckily, a few new and upcoming features exist in Python that help out with this issue. 
Pymalloc, an experimental feature added by Vladimir Marangozov in Version 2.1, is 
one of these. Pymalloc is a specialized object allocator that actually utilizes C's 
malloc () (short for memory allocation) function to get large pools of memory and then 
fili smaller requests for memory from these pools. Since Pymalloc is optional in 
Version 2.1 and 2.2, you need to include an option to the configure script (in the form of 
--with-pymalloc) in order to use it. Python Version 2.3 or higher enables it by default. 

Pymalloc works by dividing memory requests into size classes (see Figure 3.6). These 
classes range from eight to 256 bytes and are spaced eight bytes apart. Memory requests 
lie within 4k pools that hold requests. Pymalloc allocates and deallocates requests for 
memory from these classes within pools. When deallocating Pymalloc memory classes, 
the classes can be completely freed (using f ree ()) or released back into their respective 
pools. When the pools are empty, they are also released back into the memory at large. 

Figure 3.6. Pymalloc doles out memory requests 



NOTE 
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CAUTION 


Pymalloc is meant to be transparent, but it may expose so-far-unknown bugs when used 
with C extensions. There have already been doeumented problems using Pymalloe with 
Python's C API. Use with eaution. 

Besides Pymalloe, in Version 2.3 Python has depreeated the previous API for dealing 
with memory and has new funetions, some under PyMem, for alloeating memory by 
bytes or type, and some under PyObjeet for alloeating memory speeifically for objects. 

Performance and Speed 

If you write Python eode to do eomplex numerieal work and then eompare the results to 
those done with C++, you will be disappointed. The plain truth is that Python is a 
slower language. In Python, every variable referenee is a hash table lookup, and so is 
every function eall. This eannot eompete with C++, in whieh the loeations of variables 
and funetions are decided at eompile time. 

However, this does not mean that Python is not suitable for game programming; it just 
means that you have to use it appropriately. For instanee, if you are doing string 
manipulations or working with maps, Python may aetually be faster than C++. The 
Python string manipulation funetions are aetually written and optimized in C, and the 
referenee-eounted objeet model for Python avoids some of the string eopying that ean 
oeeur with the C++ string elass. 

And, as I mentioned before, even if you don't think you should write your polygon 
collision detection eode in Python, you may want to write your AI eode and game loop 
in Python and prototype the eollision deteetion. Then, after benehmarking, you ean 
write the eollision deteetion in C++ and expose it to Python. This will make eoding 
mueh faster for you. 

The Python prof ile module ean be used to profile sets of funetions. If you had a 
funetion ealled MyFunction stored in MyModule, the function ean be imported into new 
script or the Python interpreter and then profiled by running: 


import MyModule 

profile.run('MyFunction () ') 


Python's profile module prints a table of all the function calls and each function calfs 
execution time. Python also possesses a useful trace module that ean be used to trace 
the execution of Python Scripts. 

You'll find that most folks will argue against using Python in games for speed-related 
issues more than any other. Here are a few performance tips to wrap up the chapter and 
to keep in mind for dealing with speed issues: 

• Python has a number of debugging tools to use for benehmarking. If you get 
used to using them, you ean easily get a feel for where things are slow in a given 
program. 
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• Be careful when using loops, since multiple iterations can easily become 
memory hogs. Systems calls should be moved outside of loops whenever 
possible (actually, Systems ealls should be avoided if at all possible). Try not to 
instantiate any objects inside of loops; doing so ean eause many copies in 
memory and lots of work for the garbage collector. 

• Use references instead of actual values when calling values, unless the values 
are very small. 

• Avoid passing long argument lists to functions and subroutines. Keep them short 
and simple. 

• Avoid reading or writing files line by line. Read them into a buffer instead. 

• Check out all the fun libraries before building a function, and in particular, pay 
close attention to what Python has built in. Your newly written function is 
probably slower than the version the community has been using for a few years. 

• Pay close attention to Chapter 12 in this book and learn how to extend Python in 
C. 

• Use the -o switch when compiling to Python to byte-code (o is short for the 
compiler optimizing mode) 

• Use aliases for imported functions instead of using the full name. Again, be 
especially careful when you do things like use full names inside of a loop. 

• C++ programmers sometimes joke about optimizing their code by making 
variable names shorter. In Python this may actually work, since Python looks up 
variables by name at runtime. 

• Avoid while loops with a loop counter. Instead use range ( ) or xrange () . The 
Python range () opcrator is fast because it actually constructs a sequence object 
over which to iterate. 

• Avoid heavy use of module-scoped variables. Locally scoped variables are 
usually faster. 

Finally, keep in mind that optimizing code can take a lot of time and effort and isn't 
always worth it. Also, optimizing may eause other, bigger problems, such as making 
code harder to maintain, harder to extend, or buggier. Only if a script is running 
hundreds of times a day, or if the code relies on speed as a requirement, is shaving a few 
seconds off of it worth the development time. 
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Summary 

Before you move on to the next chapter, make sure that Python installed correctly and 
that you ean run the Interactive environment. You should feel pretty comfy with for 
loops, while loops, and if else statemcnts. You should also have had a chance to 
poke around with Tkinter a bit, and you should know what Python's garbage collector 
does. 

Important points from this chapter: 

• Tabs, colons, and newlines are the basis for Python punctuation. 

• Python's most common data types are numbers, strings, lists, tuples, and 
dictionaries. 

• Modules ean be used to pass functions from file to file. 

• Garbage collection and other aspects ean be managed in Python if necessary. 
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Questions and Answers 


1: Q: IVe heard that the creator of Python and other writers have written 

tutorials on speeding up Python execution. Why aren't they mentioned here? 

A: A; This chapter is a quick, whirlwind introduction to the Python language and 
is not meant to be an all-inelusive guide. Both Guido van Rossum and 
Andrew Dalke have written a few great online articles on benehmarking, 
Python performance, and other topics. The Python Essays Web page is a good 
place to start looking into the topic; it's at http://www.pvthon.org/doc/essavs/ . 

2: Q: Is there more to Python graphics than just Tkinter? 

A: A: Absolutely. These are covered in the next chapter, along with a eloser look 
at the usefulness of Tkinter. 

3: Q: What about music? Does Python have any functionality for sound built in? 

A: A: Python does have libraries that work with musie and sound effects. I cover 
the Musickit library in Chapter 4. 
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Exercises 


1 : Lists use parentheses and tuples use braekets for assignments. What do 
dietionaries use? 

2: List two eseape sequenees. 

3: Name any one list method and what it does. 

4 : Write a simple example of a for loop. 

5: Define "widget." 

6: List one possible action that could slow down a program when used within an 
iteration, or loop. 

7: Write a program that takes as input two strings and two integers and then 
displays them. 
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Chapter 4. Getting Specific with Python Games 


.. .corporate methods do not have the conceptual framework to deal with an anarchist 
collective run by intelligent and arrogant comedians who have proved that their method 
Works. 

-Robert Hewison on the Monty Python group. 

Now that youVe completed Chapter 3's quick tutorial, it's time to jump into a few 
specific multimedia Python libraries and script an actual game or two. This chapter gets 
started with Python's Pygame library and moves specifically into graphics, networking, 
and sound for game programming. 
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The Pygame Library 

Pygame is a Python wrapper for the Simple DirectMedia Layer (SDL). Pygame foeuses 
on bringing the world of graphics and game programming to programmers in an easy 
and efficient way. 

Typically, Pygame projects are small, simple, two-dimensional or strategy games. In 
Chapter 5, Pll give you a close look at a few existing Pygame-based game engines, 
including Pyzzle, a Myst-like engine; PyPlace, a two-dimensional isometric engine; and 
AutoManga, a cell-based anime-style animation engine. 

Installing Pygame 

This book's CD comes with a copy of Pygame in the \PYTHON\PYGAME folder. The 
most recent versions can be found online at http://www.pvgame.org/download.shtml . 

The Windows binary installer on the CD has versions for Python 2.3 and 2.2, there is a 
Mac .sit for older Mac versions and a version for the Mac OSX, and the RPM binary 
has been included for the Red Hat operating system. Pygame actually comes with the 
most recent and Standard UNIX distributions, and can be automatically built and 
installed by the ports manager. 

On Windows, the binary installer will automatically install Pygame and all the 
necessary dependencies. A large Windows documentation package, along with sample 
games and sample code, is available at the Pygame homepage at 
http://www.pvgame.org . 

Pygame also requires an additional package, called the Numeric Python package, in 
order to use a few of its sleeker and quicker array tools. This package can be found in 
the Python section of the accompanying CD. At this time, the creators of Numeric 
Python are working 

NOTE 

SDL 

SDL is considered an altemative to Direct X especially on Linux machines. As a 
multimedia and graphics library, SDL provides low-level access to a computefs video, 
sound, keyboard, mouse, and joystick. 

SDL is similar in structure to a very rudimentary version of Microsoffs Direct X API, 
the big difference being that SDL is open source, supports multiple operating Systems 
(including Linux, Mac, Solaris, LreeBSD, and Windows), and has an API binding to 
other languages, including Python. 

SDL is written in C and available under the GNU Lesser General Public License. Sam 
Lantinga, who worked for both Loki Software and Blizzard entertainment, is the genius 
behind SDL. He got his start with game programming in college by porting a Macintosh 
game called Maelstrom to the Linux platform. 
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Sam was working on a Windows port of a Macintosh emulator program called Executor 
and figured that the code he was building to extract the emulator's graphics, sound, and 
controller interface could be used on other platforms. Late in 1997 he went publie with 
SDL as an open-source projeet, and since then SDL has been a eontender. 

on an even faster version ealled Numeric. If you need to install the Numeric paekage, 
use the .exe for Windows or the tar.gx for Posix environments. Numerio is distributed 
under an OSI lioense just like Python itself, and the latest development oan be found at 
http://soureeforge.net/projeets/numpv . 

The Mac OS X tar includes Python 2.2, Pygamel.3 (hacked for Macs), PyOpenGL, and 
Numeric. There are stili some bugs and issues with SLD oompatibility on pre-OS X and 
post-OS X, and a simple installer for the Mae that should fix most of these issues is 
planned for when Python 2.3 is released. 

NOTE 

CAUTION 

Do not use stuffit to untar the paekage on Mac OS X. Stuffit will truncate some of the 
larger filenames. 

Pygame is distributed under the GNU LGPL, lioense Version 2.E See Figure 4.1 for a 
shot of Pygame installation. 

Figure 4.1. Installing Pygame 



Using Pygame 

Pygame itself is fairly easy to leam, but the world of oomputer games and graphios is 
often unforgiving to beginners. Pygame has also suffered oritioism for its laok of 
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documentation. This lack of documentation leads many new developers to browse 
through the Pygame package, looking for information. However, if you browse through 
the package, you will find an overwhelming number of classes at the top of the index, 
making the package seem confusing. The key to starting with Pygame is to realize that 
you can do a great deal with just a few functions, and that you may never need to use 
many of the classes. 

Importing Pygame 

The first step towards using Pygame after it has been installed is to import the Pygame 
and other modules needed for development into your code. Do the following; 

import os, sys 
import pygame 

from pygame.locals import * 


Keep in mind that Python code is case-sensitive, so for Python, Pygame and pygame are 
totally different creatures. Although I capitalize Pygame in this book's text, when 
importing the module, pygame needs to be in ali lowercase letters. 

First import a few non-Pygame modules. You'll use the os and sys libraries in the next 
few examples for creating platform independent files and paths. Then import Pygame 
itself When Pygame is imported, it doesn't actually import ali of the Pygame modules, 
as some are optional. One of these modules, called locals, contains a subset of Pygame 
with commonly used functions like rect and quit in the easy-to-access global 
namespace. For the upcoming examples the locals module will be included so that 
these functions will be available as well. 

NOTE 

TIP 

The Pygame code repository is a community-supported library of tools and code that 
utilizes Pygame. The source code is managed by Pygame, but submissions are from 
users of the library. The repository holds a number of useful code snippets—everything 
from visual effects to common game algorithms—and can be found at 
http://www.pvgame.org/pcr/ . 

The Pygame Surface 

The most important element in Pygame is the surface. The surface is a blank slate, and 
is the space on which you place lines, images, color, and so on. A surface can be any 
size, and you can have any number of them. The display surface of the screen is set 
with: 

Pygame.display.set_mode() 


113 



You can create surfaees that have images with image. load (), surfaees that eontain text 
with font. render (), and blank surfaees with Surface (). There are also many surfaee 
funetions, the most important being blit (), fili (), set_at (), and get_at (). 

The surfaee. convert () command is used to eonvert file formats into pixel format; it 
sets a JPEG, GIF, or PNG graphio to individual oolors at individual pixel looations. 

NOTE 

TIP 

Using surfaee.eonvert is important so that SDL doesn't need to eonvert pixel formats 
on-the-fiy. Converting all of the graphio images into an SDE format on-the-fiy will 
cause a big hit to speed and performanoe. 

Eoading a surfaee image is fairly simple; 

My Surfaee = pygame.image.load('image.jpeg') 


as is oonverting an image: 

My_Surface = 

pygame.image.load('image.jpeg').convert() 


A oonversion only needs to be done onoe per surfaee, and should inorease the display 
speed dramatioally. 

Drawing on the display surfaee doesn't actually cause an image to appear on the soreen. 
For displaying, the pygame. display. update () oommand is used. This oommand oan 
update a window, the full soreen, or certain areas of the soreen. It has a oounterpart 
oommand, pygame. display . f lip (), whioh is usod when using double-buffered 
hardware aooeleration. 

NOTE 

CAUTION 

The convert () oommand will aetually rewrite an image's intemal format. This is good 
for a game engine and displaying graphios, but not good if you are writing an image- 
conversion program or a program where you need to keep the original format of the 
image. 

Creating a Pygame Window 

Creating a window in which Pygame oan run an applioation is fairly easy. First you 
need to start up Pygame with an initialize oommand; 

pygame.init() 
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Then you can set up a window with a caption by using Pygame's display command; 
My_Window = pygame.display.set_mode((640, 480)) 


This code run by itself (the code is included as the My_window.py example in this 
chapteds code section on the CD) creates a 640x480-pixel window labeled Pygame 
Window, just like in Figure 4.2. Of eourse, the window accomplishes nothing, so it 
immediately disappears after showing up on the screen. 

Figure 4.2. A simple Pygame window 



The Ever-Important rectQ 

The most used class in Pygame probably the rect () elass, and it is the second most 
important concept in Pygame. rect 0 is a class that renders a rectangle: 

My_Rectangle = pygame.rect() 


rect () comes with utility funetions to move, shrink, and inflate itself; flnd a union 
between itself and other rects; and deteet collisions. This makes rect () an ideal class 
for a game object. The position of a rect () is defmed by its upper-left eorner. The code 
that rects use to deteet overlapping pixels is very optimized, so you will see rects 
used in sprite and other sorts of collision deteetion. For eaeh objeet, there will often be a 
small rect () undemeath to deteet collisions. 

The Event System 
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In order for Pygame to respond to a player or user event, you normally set up a loop or 
event queue to handle incoming requests (mouse clicks or key presses). This loop is a 
main while loop that eheeks and makes sure that the player is stili playing the game: 

stili playing = 1 

while (stili playing==l): 

for event in pygame.event.get(): 
if event.type is QUIT: 

stili playing = 0 


The for event line uses pygame. event. get () to get input from the user. Pygame 
understands basie Windows eommands, and knows that quit is equivalent to pressing 
the X at the top right eorner of a ereated window. The pygame. event funetion is used to 
handle anything that needs to go into the event queue—whieh is basieally input from 
any sort of deviee, be it keyboard, mouse, or joystiek. This funetion basieally ereates a 
new event objeet that goes into the queue. The pygame. event. get funetion gets events 
from the queue. The event members for pygame. event are 

• QUIT. Quit or Close button. 

• ACTIVEEVENT, Contains state or gain. 

• KEYDOWN, Unieode key when pressed. 

• KEYUP. Uneode key when released. 

• MOUSEMOTION, Mouse position. 

• MOUSEBUTTONUP. Position mouse button releases. 

• MOUSEBUTTONDOWN. Position mouse button pressed. 

• JOYAXISMOTION. Joystiek axis motion. 

. JOYBALLMOTION. Traekball motion. 

• JOYHATMOTION. Joystiek motion. 

• JOYBUTTONUP. Joystiek button release. 

• JOYBUTTONDOWN. Joystiek button press. 

• VIDEORESIZE, Window or video resize. 

• VIDEOEXPOSE, Window or video expose. 

• USEREVENT, Coded user event. 

These are normally used to traek keyboard, mouse, and joystiek aetions. Lefs say you 
wanted to build in mouse input handling. AU mouse input is retrieved through the 

pygame. event module. 

If event.type Is MQUSEBUTTQNDOWN: 

# do somethlng 


Pygame also has a number of methods to help it deal with aetual mouse position and 
use; these are listed in Table 4.1. 


Method 

get_cursor 


Table 4.1. Pygame Mouse Event Methods 
Purpose 

Gets the mouse eursor data 
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Method 

Table 4.1. Pygame Mouse Event Methods 

Purpose 

get focused 

Gets the state of the mouse input focus 

get pos 

Gets the cursor position 

get pressed 

Gets the state of the mouse buttons 

get rei 

Grabbing mouse movement 

set cursor 

Sets the state of the shape of the mouse cursor 

set pos 

Moves the cursor 

set visible 

Displays or hides the mouse cursor 


You can check the state of a mouse or keyboard event by using 

pygame .mouse . get_pos () or pygame . key. get_pressed (), respectively. 


Drawing with Pygame 

Pygame has great built-in functions for graphics. These funetions revolve around the 
idea of the surfaee, whieh is basieally an area that ean be drawn upon. Lef s say you 
wanted to fili the baekground in My_window.py with a color. First grab the size of the 
window: 

My Baekground = pygame.Surfaee(My_Window.get_size()) 


This creates a surfaee called My_Baekground thafs the exact size of My_window. Next 
convert the surfaee to a pixel format that Pygame can play with: 

My Baekground = My Baekground.eonvert() 


And finally, fili the baekground with a color (set with three RGB values): 


My Baekground.fili((220,220,80)) 


Now lef s do some drawing over the baekground surfaee. Pygame comes with a draw 
function and a line method, so if you wanted to draw a few lines, you could do this: 

pygame.draw.line (My_Baekground, (0, 0,0,), (0,240), (640,240), 5) 
pygame.draw.line (My_Baekground, (0,0,0), (320,0), (320,480), 5) 


Pygame's draw. line takcs five parameters. The first is the surfaee to draw on, the 
second is what color to draw (again in RGB values), and the last is the pixel width of 
the line. The middle parameters are the start and end points of the line in x and y pixel 
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coordinates. In this case, you draw the thick lines erossing in the exaet eenter of the 
window, as shown in Figure 4.3. 

Figure 4.3. Pygame's draw. iine is used to split My_window into four sections 



The easiest way to display the baekground and lines is to put them into a draw funetion: 

def draw stuff(My Window): 

My Baekground = pygame . Surface (My Window. get sizeO) 

My Baekground = My Baekground.convert() 

My Baekground.fili((220,220,80)) 

pygame.draw.line (My_Background, (0,0,0,), (0,240), (640,240), 5) 

pygame.draw.line (My_Background, (0,0,0), (320,0), (320,480), 

5) 

return My_Background 

Then eall the funetion within the loop that exists (and illustrated as eode sample 

My Window 3 . py On the CD); 

My Display = draw stuff(My Window) 

My_Window.blit(My Display, (0,0)) 
pygame.display.flip() 


Blitting 

Blitting (Bloek Image Transfering) is praetieally synonymous with rendering, and 
speeifically means redrawing an object by eopying the pixels of said object onto a 
sereen or baekground. If you didn't run the blit () method, nothing would ever get 
redrawn and the sereen would just remain blank. For those of you who must know, blit 
isn't a made-up word—it's short for "bit bloek transfer." 
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In any game, blitting is often a process that slows things down, and paying attention to 
what you are blitting, when you are blitting, and how often you are blitting will have a 
major impaet on your game's performance. The key to a speedy graphics engine is 
blitting only when neeessary. 

The blit method is very important in Pygame graphies. It is used to copy pixels from a 
souree to a display. In this ease, biit takes the pixels plotted in My_Dispiay (which 
took the eommands from draw_stuf f) and eopies them to My_window. The blit 
method understands speeial modes like colorkeys and alpha, it ean use hardware support 
if available, and it ean also earry three-dimensional objects in the form of an array 
(using blit_array () ). In this example, blit is taking My_Display as the input and 
rendering it to My_window, and it uses the upper-left eorner (pixel 0,0) to key up the 
surface. 

The pygame. display. f lip () command is Pygame's built-in funetion for updating the 
entire display (in this case, the entirety of My_window) once any graphio changes are 
made to it. 

NOTE 

TIP 

In Windows, you ean add a single "w" to the end of a Python file (so that instead of 
ending it in py, it ends in pyw) to make the program open up a window without opening 
up the interpret console, that funny-looking DOS box. 

Loading an Image with Pygame 

Image loading is an oft-needed funetion in games; in this section TU show you the steps 
for loading an image in Pygame. 

After importing the neeessary modules, you need to define a funetion for loading an 
image that will take an argument. The argument will be used to set the colorkey (the 
transparency color) of the image; it looks like this: 

def load image(name, colorkey=None): 


Colorkey blitting involves telling Pygame that all pixels of a specific color in an image 
should be transparent. This way, the image square doesn't block the background. 
Colorkey blitting is one way to make non-rectangular, two-dimensional shapes in 
Pygame. The other common trick is to set alpha values using a graphics program like 
Adobe Photoshop, as illustrated in Figure 4.4 and explained in the following sidebar. 

Figure 4.4. Setting alpha values using Adobe Photoshop 
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To turn colorkey blitting on, you simply use surface. set_colorkey (color) . The 
eoior fed to surface. set_coiorkey is three-digit tuple (0,0,0) with the first number 
being the red value, the seeond green, and the third blue (that is, rgb). 

NOTE 

Colorkey versus Alpha 

Both colorkey and alpha are techniques for making parts of a graphio transparent when 
traveling across the screen. In Pygame, most 2D game objects and sprites are rects, and 
are rectangular in shape. This means you need a way to make part of the rectangle 
transparent, so that you can have circular, triangular, or monkey-shaped game pieces. 
Otherwise you would only be capable of displaying square pieces over a background. 

Alpha is one technique for making parts of an image transparent. An alpha setting 
causes the source image to be translucent or partially opaque. Alpha is normally 
measured firom 0 to 255, and the higher the number is the more transparent the pixel or 
image is. Alpha is very easy to set in a graphio editor (like Adobe Photoshop), and 
Pygame has a built-in get_alpha () command. There is also per-pixel alpha where you 
can assign alpha values to each individual pixel in a given image. 

When using a colorkey technique (sometimes called colorkey blitting) you let the image 
renderer know that all pixels of one certain color are to be set as transparent. Pygame 
has a built-in colorkey (color) function that takes in a tuple in the form of RGB. For 
instance, set_colorkey (0,0,0) would make every black pixel in a given image 
transparent. 

You'll use both techniques in this chapter. The load_image function in this section uses 
set_colorkey (), whllc the load_image command in the MorLkey_Toss.py graphics 
example later on in the chapter uses get_aipha. 
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The module needs to know where to grab the image, and this is where the os module 
comes into play. You'll use the os path function to create a full pathname to the image 
that needs to be loaded. For this example, say that the image is located in a "data" 
subdirectory, and then use the os. path. j oin function to create a pathname on 
whatever system (Mac, Windows, UNIX) that Python is running on. 

fullname = os.path.join('data', name) 


Try/except Code Blocks 

Being able to fail gracefully is important in programming. Basically, you always need to 
leave a back door, or way out of a program, for if an error occurs. You'll find that 
try/except or try/finally constructs arc vcry common. 

Python offers a try/except/else construet that allows developers to trap different 
types of errors and then execute appropriate exception-handling code. try/except 
actually looks just like a series of if/elif/else program flow commands: 


try: 

execute 
except errori: 

execute 
except error2: 

execute 

else: 


execute 


this block 
this block if 
this block if 
this block 


"errori" 
"error2" 


is generated 
is generated 


This structure basically allows for the execution of different code blocks depending on 
the type of error that is generated. When Python encounters code wrapped within a try- 
except- else block, it first attcmpts to execute the code within the try block. If this 
code Works without any exceptions being generated, Python then checks to see if an 
else block is present. If it is, that code is executed. 

If a problem is encountered while running the code within the try block, Python stops 
execution of the try block at that point and begins checking each except block to see if 
there is a handler for the problem. If a handler is found, the code within the appropriate 
except block is cxccuted. Otherwise, Python jumps to the parent try block, if one 
exists, or to the default handler (which terminales the program). 

A try/except Structure is used to load the actual image using Pygame's image.load. Do 
this through a try/except block of code in case there is an error when loading the 
image: 


try: 

image=pygame.image.load(fullname) 
except pygame.error, message: 

print 'Cannot load image:', name 
raise SystemExit, message 
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Once the image is loaded, it should be converted. This means that the image is copied to 
a Pygame surface and its color and depth are altered to match the display. This is done 
so that loading the image to the screen will happen as quickly as possible: 

image=image.convert() 


The next step is to set the coiorkey for the image. This can be the coiorkey provided 
when the function was called, or a -l. If the -l is called, the value of coiorkey is set to 
the top-left (0,0) pixel. Pygame's coiorkey expects an RGBA value, and rleaccel is a 
flag used to designate an image that will not change over time. You use it in this case 
because it will help the speed of the image being displayed, particularly if the image 
must move quickly. 

if coiorkey is not None: 

if coiorkey is -1: 

coiorkey = image.get_at((0,0)) 
image.set coiorkey(coiorkey, RLEACCEL) 


The final step is to retum the image object as a rect (Like fve said, Pygame is based on 
rects and surfaces) for the program to use: 

return image, image.get_rect() 


The full code snip for load_image is listed here and also on the CD, as 

Load Image.py: 

def load image(name, colorkey=None): 

fullname = os.path.join('data', name) 
try: 

image=pygame.image.load(fullname) 
except pygame.error, message: 

print 'Cannot load:', name 
raise SystemExit, message 
image=image.convert() 
if coiorkey is not None: 

if coiorkey is -1: 

coiorkey = image.get_at((0,0)) 
image.set_colorkey(coiorkey, RLEACCEL) 
return image, image.get rect() 


Displaying Text 

Pygame has, of course, methods for dealing with text. The pygame. f ont method allows 
you to set various font Information attributes: 

My Font = pygame.font.Font(None, 36) 
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In this case, you set up a My_Font variable to hold Font (None, 36) , which establishes 
no particular font type (None, whieh will eause a default font to be displayed) and a 36 
font size (36). Step 2 is to ehoose what font to display using font. render: 

My Text = font.render("Font Sample", 1, (20, 20, 220)) 


The arguments passed to font. render inelude the text to be displayed, whether the text 
should be anti-aliased (1 for yes, 0 for no), and the RGB values to determine the texfs 
color. The third step is to plaee the text in Pygame's most useful rect (): 

My_Rect = My_Text.get_rect() 


Finally, you get the eenter of both rect () s you ereated and the baekground with 
Python's super-speeial centerx method (whieh is simply a method for determining the 
exaet eenter of something), and then eall the blit () method to update: 

My Rect. centerx = My_Back;ground. get_rect (). centerx 
baekground.blit(My Text, My_Rect) 


A Pygame Game Loop 

A Pygame game loop is usually very straightforward. After loading modules and 
defining variables and funetions, you just need a loop that looks at user input and then 
updates graphies. This ean be done with only a few lines of eode. A typieal event loop 
in a game would look something like this: 

while 1: 

for event in pygame.event.get(): 
if event.type == QUIT: 

#exit or quit function goes here 
return 

screen.blit(MY Window, (0, 0)) 
pygame.display.flip() 


The pygame . event module looks for USer input, and pygame . blit and 
pygame. display keep the graphics going. Lefs say, for example, that you wanted to 
look speeifieally for up or down arrow keys for player eontrol. To do so, you eould 
simply add elif statements to the event loop: 

while 1: 

for event in pygame.event.get(): 
if event.type == QUIT: 

#exit or quit function goes here 
return 

# Add to listening for arrow keys In the event queue 
elif event.type == KEYDOWN: 

If event.key == K UP 

# do something 
If event.key == K_DOWN 

# do something 
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screen.blit(MY Window, (0, 0)) 
pygame.display.flip() 


Pygame Sprites 

Originally computers were simply incapable of drawing and erasing normal graphics 
fast enough to display in real-time for purpose of a video game. In order for games to 
work, special hardware was developed to quickly update small graphical objects, using 
a variety of special techniques and video buffers. These objects were dubbed sprites. 
Today sprite usually refers to any animated two-dimensional game object. 

Sprites were introduced into Pygame with Version 1.3, and the sprite module is 
designed to help programmers make and control high-level game objects. The sprite 
module has a base class Sprite, firom which all sprites should be derived, and several 
different types of Group classes, which are used as Sprite containers. 

When you create a sprite you assign it to a group or list of groups, and Pygame 
instantiates the sprite game object. The sprite can be moved, its methods can be 
called, and it can be added or removed from other groups. When the sprite no longer 
belongs to any groups, Pygame cleans up the sprite object for deletion (altemately, 
you can delete the sprite manually using the kill () method). 

The Group class has a number of great built-in methods for dealing with any sprites it 
owns, the most important being update (), which will update all sprites within the 
group. Several other useful group methods are listed in Table 4.2. 


Method 

add () 
copy() 
empty() 
len () 
remove() 
truth() 
update() 


Table 4.2. Useful Group Methods 

Use 

Adds a sprite to the group 

Makes a copy of the group with all of its members 

Removes all sprites within the group 

Returns how many sprites the group contains 

Removes sprite from the group 

Returns true if group has any sprites 

Calis an update method on each sprite within the group 


Groups of sprites are very useful for tracking game objects. For instance, in an asteroid 
game, player ships could be one group of sprites, asteroids could be a second group, and 
enemy starships a third group. Grouping in this way can make it easy to manage, alter, 
and update the sprites in your game code. 

Memory and speed are the main reasons for using sprites. Group and sprite code has 
been optimized to make using and updating sprites very fast and low-memory 
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processes. Pygame also automatically handles cleanly removing and deleting any 
sprite objects that no longer belong to any groups. 

Updating an entire screen each time something changes can cause the frames-per- 
second rate to dip pretty low. Instead of updating the entire sereen and redrawing the 
entire sereen normally, an engine should only ehange the graphies that have aetually 
ehanged or moved. The engine does this by keeping traek of whieh areas have ehanged 
in a list and then only updating those at the end of eaeh firame or engine eyele. To help 
out in this proeess, Pygame has different types of groups for rendering. These methods 
may not work with a smooth-serolling, three-dimensional, realtime engine, but then 
again, not every game requires a whopping frame-rate. Pygame's strength lies 
elsewhere. 

Besides the Standard Group elass there is also a GroupSingle, a RenderPlain, a 
RenderClear, and a RenderUpdates olaSS (see Figure 4.5). GroupSingle oan only 
eontain one sprite at any time. Whenever a sprite is added to GroupSingle, any existing 
sprite is forgotten and set for deletion. RenderPlain is used for drawing or blitting a 
large group of sprites to the screen. It has a specific draw () method that tracks sprites 
that have image and rect attributes. RenderPlain is a good choice as a display engine 
for a game that scrolls through many backgrounds but not any rects, like scrolling 
games where the player stays in a consistent area of the screen and the background 
scrolls by to simulate movement. RenderClear has all the functionality of 
RenderPlain but also has an addcd ciear () mcthod that uses a background to cover 
and erase the areas where sprites used to reside. RenderUpdates has all the 
functionality of RenderClear, and is also capable of tracking any rect (not just sprites 
with rect attributes) for rendering with draw (). 

Figure 4.5. Sprite Container ciasses 
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Sprites also have built-in collision detection. The spritecollide () method checks for 
collisions between a single sprite and sprites within a speeific group, and will retum a 
list of all objeets that overlap with the sprite if asked to. It also eomes with an optional 
dokill flag, whieh, if set to true, will call the kill () method on all the sprites. 

A groupcollide () method cheoks the eollision of all sprites between two groups and 
will return a dietionary of all eolliding sprites if asked to. Finally, the 
spritecollideany () method retums any single sprite that collides with a given sprite. 
The structure of these collision methods is: 


pygame.sprite.spritecollide(sprite, group, kill?) ->list 

pygame.sprite.groupcollide(groupl, group2, killgroupl?, killgroup2?) - 

> dietionary 

pygame.sprite.spritecollideany(sprite, group) -> sprite 


Here is an example of a collision that checks to see whether My_Sprite ever collides 
with My_Player, and rcmovcs the offending My_Sprite sprite: 

for My Sprite in sprite.spritecollide(My Player, My Sprite, 1): 

#What happens during the collision plays out here 


When using Pygame sprites, you need to keep a few things in mind. First, all sprites 
need to have a rect () attribute in order to use the collide () or most other built-in 
methods. Second, when you call the Sprite base class to derive your sprite, you must 
call the sprite_init_ () mcthod firom your own class_init_ () method. 

Game Object Classes 

Python being a pseudo-object-oriented language, normally game classes are created 
first, then speeific instances of game objeets are initiated firom the created classes. Lefs 
walk through creating an example class, a banana: 

class Banana: 

# init method 
# banana method 

# banana method 2 

# banana method 3 

def main 

My Banana = Banana() 


This is roughly how a class works. The Banana class needs at least an _init_ method, 
and will likely contain many more. After the class is created, simply call the class to 
create an instance called My_Banana in the main loop. 

Since an _init_ method is mandatory, lefs take a look at what that method would look 
like first: 


126 



class Banana(pygame.sprite.Sprite): 
def _init_(self): 

pygame.sprite.Sprite._Init_(self) 


The Banana class is set up as a Pygame sprite. When you detine the _init_ method, 
you must speeify at least one parameter that represents the objeet of the elass for whieh 
the method is called. By eonvention, this referenee argument is ealled self. 

You may want to add other speeifications to the _init_ method. For instanee, you may 
wish to speeify an image/rect and load up a graphio. You may also want to tie the 
Banana class to the soreon: 

class Banana(pygame.sprite.Sprite): 
def _init_(self): 

pygame.sprite.Sprite._Init(self) 

self.Image, self.rect = load png('banana.png') 

screen = pygame.display.get_surface() 


After defining init_, you may also want to add methods that de fine the objeofs 
position on the soreen, and update the objeet when neoessary: 

class Banana(pygame.sprite.Sprite): 
def _init_(self): 

pygame.sprite.Sprite._Init(self) 
self.Image, self.rect = load png('banana.png') 
screen = pygame.display.get_surface() 
def Bannana Position(self, rect) 

# Funky math here 

# that defines position on screen 
return position 

def Banana_Update(self) 

# Code that updates the banana 


Pygame Dra wbacks 

Pygame is simply a wrapper around SDL, whieh is a wrapper around operating system 
graphio oalls. Although programming is muoh easier when using Pygame than when 
using SDL, Pygame removes you pretty far from the oode that aotually does the work, 
and this oan be limiting in a number of ways. 

Probably the most signifioant drawbaok to Pygame, however, is the faot that the library 
needs so many dependenoies in order to function. Obviously, Pygame needs Python and 
SDL to run, but it also needs several smaller librarios, inoluding SDL_ttf, SDL_mixer, 
SDL_image, SDL rotozoom, and the Python Numerio paokage for the surfarray 
module. Some of these librarios have their own dependenoies. 

UNIX packages generally oome with paokage and dependenoy managers that make 
managing dependenoies a oontrollable problem in UNIX. But on Windows Systems, it 
oan be diffioult to distribute a game without oreating a oolleotion of all the needed files 
the game requires to run. 
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Luckily, there are Python tools to help build Windows executables. I mentioned a few 
of these in Chapter 3, in particular a tool called Py2exe. Pete Shinners, the Pygame 
author, actually wrote a tutorial on how to use Py2exe to paekage a Python Pygame for 
Windows. The tutorial comes with a sample distutils script and can be found at 
http://www.pvgame.org/docs/tut/Executable.html . 

Finally, although hardware acceleration is possible with Pygame and fairly reliable 
under Windows, it can be problematic because it only works on some platforms, only 
Works full screen, and greatly complicates pixel surfaces. You also can't be absolutely 
sure that the engine will be faster with hardware acceleration—at least not until youVe 
run benchmark tests. 

A Pygame Example 

In this section you'll use the Pygame load image function with game loops to create a 
simple two-dimensional graphics-engine game example. The steps you need to take are 
as follows: 

1. Import the necessary libraries. 

2. Deline any necessary functions (such as load_image). 

3. Defme any game object classes (sprites, game characters). 

4. Create a main event loop that listens for events. 

5. Set up Pygame, the window, and the background. 

6. Draw and update necessary graphics (utilizing groups and sprites). 

I envision a monkey-versus-snakes game, where the monkey/player throws bananas at 
snakes to keep them at bay. The steps for coding this example are explained in each of 
the following sections, the full source code can be found on the CD as 
Monkey_Toss .py, and Figurc 4.6 gives you a preview of the game. 

Figure 4.6. A preview ofMonkey_ Toss.py 
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Importing the Necessary Libraries 

Importing has been covered ad nauseum already, so I will not bore you with the details. 
Simply start with this code: 


# Step 1 - importing the necessary librarias 
import pygame, os 
import random 

from pygame.locals import * 


These libraries should be familiar to you with the exception of the random module. 
Python comes equipped with random, and we will be using the random. randrange 
method to generate random numbers. 

NOTE 

Random Library 

The random. randrange method gcnerates a random number (an integer) within the 
range given. For instance, this snippet prints a number between 1 and 9; 


import random 

Print ( random.randrange(1, 10)) 


Simple enough. Note that random. randrange prints up to the highest number given, 
but not the actual highest digit. Random numbers are used so often in games that you 
will often encounter random number functions like this: 

Def DiceRoll() : 

Dicel = random.randrange( 1, 7) 

Print "You rolled %d" % (dicel) 

Return dicel 
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You will be using random's randrange () and seed () methods to produce random 
numbers for the Monkey_Toss .py example. 


DcHning Necessary Functions 

You will be using a version of load_image in this game example, but you will switeh 
from using colorkey and look instead for alpha values in the graphies. You have the 
graphies already built with alpha ehannels and stored in a data directory next to the 
game eode (and also on the CD). This means you need to alter a few lines of eode from 

Load_Image.pyl 

def load image(name): 

fullname = os.path.join('data', name) 
try: 

image = pygame.image.load(fullname) 

# Here instead of the colorkey eode we check for alpha values 
if image.get_alpha is None: 

image = image.convert() 

else: 

image = image.convert alpha() 
except pygame.error, message: 

print 'Cannot load image:', fullname 
raise SystemExit, message 
return image, image.get rect() 


You will also detine a very short function to help handle keystroke events from the 
player. We will eall this funetion AllKeysUp: 

def AllKeysUp(key): return key.type == KEYUP 


Defining Game Object Classes 

First you will defme a sprite elass. The elass needs, of eourse, an _init_ method: 

class SimpleSprite(pygame.sprite.Sprite): 
def init (self, name=None): 

pygame.sprite.Sprite._init_(self) 

if name: 

self.image, self.rect = load image(name) 

else: 

pass 


When initiating, you set SimpleSprite to load the given image name and become a 
rect (). Normally, you would inelude error eode in ease the name isn't passed or 
something else goes wrong, but for now you will just use Python's pass eommand 
(pass is an empty statement that ean be used for just such a situation). 

You will also give your SimpleSprite a method to set up its surfaee: 
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def set_image(self, newSurface, newRect=None): 
self.image = newSurface 
if newRect: 

self.rect = newRect 

else: 

pass 


Normally you would set up each pass default and also include at least a base method for 
updating the sprite, but for now lef s keep it easy. 

For this engine, as I said, I envisioned a monkey versus snakes game, and sinee you are 
writing in Python, start with the Snake_Grass elass: 

class Snak;e_Grass: 

def init (self, difficulty): 
global snakesprites 
global block 
for i in range(lO): 

for j in range(random.randrange(0, difficulty*5) ) : 
block = SimpleSprite("snake.png") 
block.rect.move_ip(((i + 1)*40), 480 - (j*40)) 
snakesprites.add(block) 

def ciear(self): 

global snakesprites 
snakesprites.empty() 


There are two methods in this class, one to initiate the objeet and one to elear it. The 
ciear () method simply uses empty () to ciear out the global snakesprites when it is 
time. The init method takes in the required self and also a measure of diffieulty, 
ensures snakesprites and block are ereated, and then starts iterating through a for 
loop. 

The outer for loop iterates through a second inner for loop that ereates a random 
number of "bloeks," eaeh of whieh eontains a square snakespritesloaded with the 
snake.png graphie. These sprites are ereated and moved into staeks on the game board 
using a bit of eonfusing math (block. rect .move_ip (((i + l)*40),480-(j*40))). 
Don't worry too mueh about the math that plaees these sprites on your 480 pixel-wide 
surfaee; instead, realize that when initiated with an integer representing diffieulty, a 
Snake_Grass object will ereate a playing board similar to that in Figure 4.7. 

Figure. Figure 4.7 snake_Grassobject called with a difUcuity of2 
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The placement of the snakesprites and the height of the rows are random so that a 
differ ent game board surface is produced each time the game is run. 

Detine the player sprite next; this will be Monkey_Sprite. You want the 
Monkey Sprite to possess the ability move in the game, so you need to detine a 
number of methods to detine and track movement; 

class Monkey_Sprite(pygame.sprite.Sprite): 
def init (self, game): 

# For creating an Instance of the sprite 
def update(self): 

# Update self when necessary 
def check_crash(self) : 

# Check for collision with other sprites 
def move(self) : 

# How to move 

def signal key( self, event, remainingEvents ): 

# Respond to player If they me to do something 
def check land(self): 

# See If reach the bottom of the screen 


Thafs a lot of methods, but in aetuality, the Monkey_Sprite is fairly uncomplicated 
once you take the time to walk through each method. Lets start with _init_: 

def init (self, game): 

pygame.sprite.Sprite._init_(self) 

self.image, self.rect = load_image('monkey.png') 
self.rightFacingImg = self.image 

self.leftFacingImg = pygame.transform.flip( self.image, 1, 0) 

self.direction = 0 
self.increment = 25 
self.oldPos = self.rect 
self.game = game 
self.listenKeys = {} 
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First you load the image into a rect () that will represent the Monkey_Sprite game 
object, monkey.png, on the game board surfaee. Then you set a number of variables. 
The rightFacingimg is the uormal State of the graphie, and the leftFacingimg is the 
graphio rotated 180 degrees using the Pygame's handy transform. flip () method. 

The s elf. direction valuo is a Booloan value that will either have the Monkey_Sprite 
traveling left (represented by a 0) or right (represented by a 1). Set self. increment to 
25, representing 25 pixels that the Monkey_Sprite will travel with eaoh update. The 
next three settings are all set for the methods that follow and use them. 

Update is the next method: 

def update(self): 

self.check land() 
self.move() 

if self.direction == 0: 

self.image = self.rightFacingimg 
else: 

self.image = self.leftFacingimg 
self.check crash() 


Update First oheoks, using the check_iand method, to see whether the Monkey_Sprite 
has reaohed the bottom of the soreen. You haven't defined check_land yet, but you will 
momentarily. Then update moves the Monkey_Sprite with the move method, whioh 
you also have yet to define. It then oheoks whioh direotion Monkey_Sprite is faoing and 
makes sure the graphie being used is faoing the oorrect way. Finally, update calls 
check_crash, whioh also noods to be defined, and oheoks to see whether there have 
been any sprite oollisions. 

The check_land method simply looks to see if the Monkey_ Sprite has orossed a 
partioular pixel boundary on the game board surfaee, whioh is defined by the 
self. rect. top and self. rect. left variablos. If it has, then we know that the 
Monkey_Sprite noods to start baok over at the top of the soreen. 

def check land(self): 

if (self.rect.top == 640) and (self.rect.left == 1): 
self.game.land() 


The move method usos the defined inorement value you set in init to move the sprite 
aoross the soreen in the direotion youVe set. If the sprite goes outside the game window 
(>640 or <0 pixels), you make the sprite switoh and travel baok aoross the soreen in the 
opposite direction: 


def move(self) : 

self.oldPos = self.rect 

self.rect = self.rect.move(self.increment, 0) 
if self.rect.right > 640: 
self.rect.top += 40 
self.increment = -25 
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self.direction = 1 
if self.rect.left < 0: 
self.rect.top += 40 
self.increment = 25 
self.direction = 0 


The check;_crash method uses Pygame's built-in group methods and 

pygame . sprite . spritecollide () to check if the Monkey Sprite ever collides with 

anything in the erash list, whieh in this ease ineludes any snakesprites. If there is a 

erash, Monkey_Sprite will eall the game. erash () method, whieh we will define 

momentarily. 

def check_crash(self): 

global snakesprites 

erash list = pygame.sprite.spritecollide(self, snakesprites, 

0 ) 

if len(crash list) is not 0: 
self.game.erash(self) 


Only one more method is assoeiated with the Monkey_ Sprite, signal_key, whieh is 
simply a listener for keyboard events. 

def signal key( self, event, remainingEvents ): 

if self.listenKeys.has key( event.key ) \ 

and event.type is KEYDOWN: 

self.listenKeys[event.key]( remainingEvents ) 


Onee a MonkeySprite objeot is loaded, it will appear in the top-left eorner of the game 
board surfaee and travel aeross the sereen, as shown in Figure 4.8. When it hits the edge 
of the sereen, it drops a little and then heads baek in the opposite direetion. If the 
Monkey_Sprite ever touehes a snakesprite or the bottom of the sereen, he will start 
baek at the top again. 

Figure 4.8. An instance of the Monkey_spr± te class travels aeross the sereen 
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Now you have monkeys and snakes. You need one more actor, a banana, which the 
Monkey_Sprite objccts will throw at and destroy the snake objects with. This means 
you need methods for the banana to update and move and check for collisions: 

class Banana(pygame.sprite.Sprite): 

def _init_(self, rect, game): 

def update(self): 
def move(self): 
def check hit(self): 


Initializing the banana sprite works much like the other _init_ methods. There will be 
an incremental value that defines how many pixels the banana moves when updated, 
and the sprite that represents the banana will load up a rect () and fili it with the 
fruit.png file. Finally, you will need some code to check with the master game object for 
when the banana collides or moves off the screen: 

def _init_(self, rect, game): 

pygame.sprite.Sprite._init_(self) 

self.increment =16 

self.image, self.rect = load image("fruit.png") 
if rect is not None: 

self.rect = rect 
self.game = game 


Updating and moving are also set up like the other classes. The banana moves according 
to its increment value and checks are required to see if the banana collides with any 
sprites or moves off of the game board surface: 

def update(self): 

self.move() 
def move(self): 

self.rect = self.rect.move(0, self.increment) 
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if self.rect.top==480: 

self.game.miss() 
else: 

self.check hit() 


Finally, the check_hit method looks for any collisions with snakesprites just like 
with the Monkey Spritel 

def check hit(self): 

global snakesprites 

collide_list = pygame.sprite.spritecollide(self, 
snakesprites,0) 

if len(collide list) is not 0: 
self.game.hit() 


There is stili one more elass to write—the most important and lengthy game objeet. You 
are aetually going to put the game eontrols and variables into a game elass ealled 
MonkeyToss. We need MonkeyToss to be able to handle a number of different things, 
but mostly keyboard events, eollisions, and aetions for when sprites move off the 
sereen. This gives MonkeyToss several different methods: 

elass MonkeyToss: 

def _init_(self, charGroup): 

def crash(self, oldPlane): 
def land(self): 
def drop_fruit(self) : 
def miss(self) : 

def signal key ( self, event, remainingEvents ) : 
def hit(self): 


The master game elass initializes pretty mueh everything else you need as far as game 
meehanies. First, it takes in the game sprites and assigns them to the charGroup group. 
Then it delines the game diffieulty that the rest of the elasses use. The speeife keybard 
key the sprite needs to respond to is the spaeebar, whieh when pressed will Tire the 
drop_f ruit method. Finally the snake, monkey, and banana (fruit) are all initialized: 

def _init_(self, charGroup): 

self.charGroup = charGroup 
self.diffieulty = 2 

self.listenKeys = {K SPACE: self.drop fruit} 
self.snake = Snake Grass(self.diffieulty) 
self.monkey = Monkey Sprite(self) 
self.charGroup.add( [self.plane] ) 
self.fruit = None 


The crash method is ealled by our Monkey Sprite when it eollides with a 
snakesprite. When the Monkey Sprite eollides with a snakesprite, it needs to be 
destroyed with the kiii () method and then a new Monkey_Sprite should be 
instantiated to start over and be assigned to the sprite group: 

def crash(self, oldMonkey) : 
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self.monkey.kill() 

self.monkey = Monkey Sprite(self) 

self.charGroup.add ([self.monkey]) 


The land method is also called by the Monkey_Sprite when it reaches the bottom of 
the screen. For this sample the method is identieal to the crash method, but in a real 
game, the landing might ereate a new field of snakes, or pop the player to a different 
area of the game entirely. 

def land(self): 

self.monkey.kill () 

self.monkey = Monkey_Sprite(self) 

self.charGroup.add([self.monkey]) 


The drop_fruit method is ealled when the spaeebar is pressed, and Monkey_Sprite 
attempts to drop fruit on a snake. Drop_f ruit assigns self. f ruit an instanee of the 
Banana elass and adds it to the aetive sprite group; 

def drop_fruit(self): 

if self.fruit is None: 

self.fruit = Banana(self.monkey.rect, self) 
self.charGroup.add([self.fruit]) 


Code must be ereated for when the dropped fruit falis past the end of the sereen; for our 
purposes the sprite ean just call the kiii () method on itself: 


def miss(self): 

self.fruit.kill() 
self.fruit = None 


For keyboard events, define a signai_key method: 

def signal key( self, event, remainingEvents ): 
if self.listenKeys.has key( event.key ): 

self.listenKeys[event.key]() 
else: 

self.monkey.signal key( event, remainingEvents ) 


The last part is the eode that handles sprite eollision. This bit is fairly eomplex. First 
you need to keep traek of all the snakesprites, and then all of the sprites in the group, 
by ereating My_Group. Then you eall colliderects [ ], whieh returns true if any rect 
in the group eollides: 

def hit(self): 

global snakesprites 

My_Group = pygame.sprite.Group() 

colliderects = [] 
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Following colliderects [ ] is a for loop that basically checks to see if the bottom of 
the fruit rect and the top of the monkey rect eollide, and if so adds them to the 
collide list: 

for i in range(3) : 

for j in range((self.fruit.rect.bottom+16- 
self.monkey.rect.top)/16): 

rect = Rect((self.fruit.rect.left-32+i*32, 

self.fruit.rect. 
bottom-j *16), (25,16)) 

colliderects.append(rect) 


Then, for eaeh eollision, you need to destroy the given fruit and make sure the sprite 
group is updated: 


for rect in colliderects: 
sprite = SimpleSprite() 
sprite.rect = rect 
My_Group.add(sprite) 

list = pygame.sprite.groupcollide(My Group, snakesprites, 

self.fruit.ki11() 
self.fruit = None 


Thaf s quite a lot of work, but, happily, defming the classes comprises the bulk of this 
sample's code, and you are past the halfway point of coding. Now onwards! 

Creating a Main Event Loop thatListens for Events 

To create a main loop, you normally define a main function containing a while loop: 


def main () : 

while 1: 

# do stuff 

if name == " main 
main () 


This ensures that main () is called and your while loop keeps running during the course 
of the game. As good coding practice, initialize a few variables inside of main (): 

global screen 
global background 
global snakesprites 
global block 


You are also going to take advantage of a Pygame clock feature and use random's seed 
method to set a random number seed. Since you are going to be experiencing movement 
and time, you'll be setting an oldfps variable to help keep track of time and loop 
iterations: 
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clock = pygame.time.Clock() 
random.seed(111111) 
oldfps = 0 


Finally, the while loop. You want to make sure time is recorded by using clocktick () 
and updating with eaeh iteration. Any keyboard events are queued, so that QUIT, the 
Eseape key, or the keyup, whieh is set to be the Spaeebar, ean be responded to: 

while 1: 

clock.tick(10) 

newfps = int(clock.get_fps0) 
if newfps is not oldfps: 

oldfps = newfps 
oldEvents = [] 

remainingEvents = pygame.event.get() 
for event in remainingEvents: 

oldEvents.append( remainingEvents.pop(0) ) 

upKeys = filter( AllKeysUp, remainingEvents ) 
if event.type == QUIT: 
return 

elif event.type == KEYDOWN and event.key == K ESCAPE: 
return 

elif event.type == KEYDOWN or event.type == KEYUP: 
game.signal_key( event, upKeys ) 


Setting Up Pygame, the Window, and the Background 

You can initialize Pygame using the init () method within main (). Then you use 
display. set mode () to configure the game surfaee to 640x480 pixels, and the game 
eaption to be "Monkey Toss". You then use your load_image method to load up the 
surfaee baekground and initialize blitting and flipping: 

pygame.init() 

screen = pygame.display.set_mode((640, 480)) 
pygame.display.set_caption('Monkey Toss') 
background, tmp rect = load image('background.png') 
screen.blit(background, (0, 0)) 
pygame.display.flip() 


Drawing and UpdatingNecessary Graphics 

For drawing, you start by initializing all of your sprites and sprite groups in main (): 

allsprites = pygame.sprite.RenderUpdates() 
snakesprites= pygame.sprite.RenderUpdates() 
block = None 

game = MonkeyToss(allsprites) 


The code that does all the work lies at the end of the while loop, whieh elears the sprite 
groups then updates and redraws eaeh ehanged rect (): 
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allsprites.ciear( screen, background) 
snakesprites.ciear(screen, background) 
allsprites.update() 

changedRects2 = allsprites.draw(screen) 

changedRectsS = snakesprites.draw(screen) 

pygame.display.update(changedRects2+changedRects3) 


The finished product and the full source code and data files can be found in Chapter 4's 
file on the CD. Obviously, quite a bit eould be added to this program. Cheek out the 
eomplete game sample at the end of this ehapter for a few ideas! 
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Python Graphics 


Choosing a graphics toolkit may be the most difficult choice when creating a game. 
There are hundreds of graphie kits to ehoose from and eaeh is very different in style and 
language. This ehapter only eovers a handful of the graphies libraries available for 
Python programming, and goes through samples in only a few of the available 
options—mainly the popular kits available for developing oross-platform. 

Speeifieally, more eoverage of Tkinter is given in this seetion, as Tkinter eomes 
bundled with Python, is eross platform, and is eommonly used as a GUI for Python 
programs. Pygame is probably the most popular Python game library in use today, and 
Pygame graphie calls have already been covered in some detail. A few OpenGL 
samples in Python are also examined at the end of this ehapter. 

NOTE 

A number of eommereial art tools are programmable with in Python seripts. Some of 
the more reeognizable tools inelude Blender, Poser, Lightflow, and Softimage XSI. 

Eaeh of these tools has a Python interfaee. Blender (i.e. gameBlender) uses Python as a 
seripting language, the Poser Pro pack includes a Python-seripting agent, Eightflow has 
a Python extension module, and Softimage is seriptable via Python. 

Eor the aspiring developer, there are also many other graphio options available. Here, 
for starters, is a short list of Python GUI libraries and graphics kits: 

• The Standard Window Interfaee. STDWIN used to be the most eommonly 
used GUI for Python, but is now largely unsupported. The library was meant to 
be a platform-independent interfaee to C-based Windows Systems, but the 
module no longer exists in Python 2.0 or above, and I mention it mainly for 
legacy. It runs under UNIX and Mae, but was never ported to Windows. 

• The Wxpython lihrary. Provides support for the wxWindows-portable GUI 
olass library. Wxpythin uses the Eesser Gnu Publio Eioense and funotions like a 
wrapper to the C++ wxWindows library. It is relatively eross platform, but not 
quite as portable as Tkinter. 

• The Pythonwin lihrary. Pythonwin is also inoluded in many Standard Python 
distributions, but applioations designed with it will only run on Windows. 
Pythonwin is a wrapper to the Miorosoft Eoundation Class Eibrary, and provides 
features of the Windows user interfaee. 

• Wpy. An objeot-oriented, oross-platform olass library system also based on the 
Miorosoft Eoundation Classes. Wpy is built to be simple and portable. 

• PyKDE. A set of Python bindings for the KDE olasses written by Phil 
Thompson. PyKDE requires Sip to run. 

. PyGTK. A firee Software GUI toolkit that has a large number of widgets 

oriented towards the X Window System. PyGTK is distributed under the Eesser 
Gnu Publio Eioense and was developed for the GTK widget and GNOME 
libraries. The library is objeot-oriented and eomes with lots of good samples. 

• GNOME Python. A set of bindings for the GNOME libraries that use PyGTK 
(whioh eomes bundled with the paokage). 

• Wafepython. Wafe is short for Widget Athena Eront End, and is a paokage for 
developing applioations with high-level graphioal user interfaoes in Tcl. 
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WafePython implements an interface between Tcl, the X Toolkit, the Athena 
Widget Set, the Motif Widget Set, and a few other classes and widget packages 
thrown in for good measure. 

• PyFLTK, FLTK stands for Fast Light Toolkit; ifs a C++ GUI toolkit for UNIX, 
OpenGL and Win32. PyFLTK was originally created to build in-house apps for 
Digital Domain. Bili Spitzak is the original author and received permission from 
the company to distribute it under the Lesser Gnu Public License. Other 
developers have done more work on the toolkit since then, and the project has 
been moved to Sourceforge. 

• Fox Python, FXPy is a C++ toolkit for developing GUIs that runs on UNIX and 
Windows; it is distributed under the Lesser Gnu Public License. Fox's emphasis 
is on speed and case of use. It uses techniques for increasing drawing speed and 
minimizing memory, and most Controls can be built with a single line of code. 
Fox supports drag and drop, OpenGL widgets, 3D graphics, and tooltips. 

• Python X. An extension that binds Python together with Motif, which is a set of 
user interface guidelines set by the Open Software Foundation. Motif is actually 
over a decade old, and there are many books covering its use, but it has been 
somewhat in decime for a while. 

• The Python Computer Graphics Kit, A collection of Python modules for 3D 
computer-graphics images. The kit mainly focuses on Pixar's RenderMan 
interface, but some modules can also be used for OpenGL programs or non- 
RenderMan-compliant renderers. 

• Vpython, A free and open-source 3D programming library designed "for 
ordinary mortals." The idea behind Vpython is case of use and simplicity. 

• Zoe, A bare-bones OpenGL graphics engine written completely in Python. Zoe 
includes only basic 3D features, and focuses on creating 3D wire-frames for 
prototyping or rapid development. 

• The PyUI Lihrary. An interface library written entirely in Python for Python. It 
can run on desktop Windows or in a 3D hardware-accelerated environment and 
is meant to be portable. PyUI was originally slated to build user interfaces for 
games. PyUI is owned by Sean Riley of Ninjaneering (see Chapter 5 for more 
information on Ninjaneering) and utilizes Python 2.1, Pygame, PyOpenGL, the 
Python Imaging Library, and the ActiveState win32 extensions. 

• PyQT, Qt for Windows is a C++ cross-platform GUI toolkit distributed by 
TrollTech, who have a free non-commercial version license and a pay 
commercial license. PyQT is a set of Python bindings to the C++ QT Toolkit, 
originally produced by the Kompany and now under River Bank Computing. 

The GUI toolkit runs on Windows, Mac OS X, and UNIX. 


NOTE 

TIP 

GUIs are created with graphical elements called widgets, which are typically scrollbars, 
buttons, text fields, etc. Widgets are normally found within a window, which Controls 
the layout of the widgets. 

Python also has a few basic built-in tools for graphics and image handling. These are 
included under its Multimedia Services modules, which are listed in Table 4.3. 
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Table 4.3. Python Multimedia Graphic Services 


Module 

colorsys 

imageop 

imghdr 

rgbimg 


Use 

Converting between RGB and other color Systems 
Manipulating raw image data 

Determining the type of image eontained in a file or bytestream 
Reading and writing image files in SGI RGB format 


The imageop module ean operate on 8- or 32-bit pixel images and has methods for 
eropping, sealing, dithering, and eonverting the image at a raw level. Colorsys ean be 
used to eonvert RGB, HLS, HSV, and YIQ eoior Systems. Python's imghdr ean 
reeognize a number of different image formats (as shown in Table 4.4) and is also 
extendable to allow even more types. 

Table 4.4. Image Formats 


Value 

Image format 

rgb 

SGI ImgLib Files 

gif 

GIF 87a and 89a Files 

pbm 

Portable Bitmap Files 

pgm 

Portable Graymap Files 

ppm 

Portable Pixmap Files 

tiff 

TIFF Files 

rast 

Sun Raster Files 

xbm 

X Bitmap Files 

jpeg 

JPEG data in JFIF Format 

bmp 

BMP Files 

png 

Portable Network Graphics 


The Tkinter Library 

In the last ehapter you built a small display box using Tkinter. Here you'll explore GUI 
ereation with Tkinter in more depth. As you reeall, Tkinter is an object-oriented 
interfaee that works on multiple platforms and is designed to be extensible so that it ean 
be used to import third-party widgets. 

Widgets 
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Tkinter comes with only a handful of Standard widgets. Each widget has a Standard set 
of methods and also supports a large set of general methods, so they are capable of a 
wide coverage. There is a lot more to widgets than whaf s listed in Chapter 3 (reprinted 
here as Table 4.5 for easy reference). This is because each of these components has its 
own place and use within a GUI, and therefore has its own components and methods 
associated with it. 


Table 4.5. Tkinter Widget Components 


Component 

Button 

Canvas 

Checkbutton 

Entry 

Frame 

Label 

Listbox 

Menu 

Menubutton 

Radiobutton 

Scale 

Scrollbar 

Text 

Toplevel 


Function 

Creates a button that triggers an event when clicked 

Displays text or images 

Creates a Boolean checkbutton 

Creates a line that accepts keyboard input 

Creates the outlying window's edge 

Displays text as labeis for eomponents 

Creates a list of options 

Creates a multiple-selection display 

Creates a pop-up or pull-down style menu 

Creates a single option button 

Creates a slider that can choose from a range 

Creates a scrollbar for other components 

Creates a multiple-line box that accepts user input 

A widget Container like Frame but with its own top-level window 


NOTE 

Tcl/TK 

TK is a toolkit that handles the creation of Windows, GUI events (widgets), and user 
interaction. The TK toolkit is provided as an extension for Tcl. Tkinter is an interface to 
Tei; without the interfaee it would take hundreds of lines of code to do even simple 
things like open a window or ereate a button. 

Many languages use or are capable of using TK. Tkinter is Python's behind-the-scenes 
director of the TK GUI toolkit, and Tcl is the behind-the-scenes director that Tkinter 
uses to communicate to TK. Both TK and Tcl are open-source developments that are 
under development at seriptics (the Tcl developer exchange can be found at 
http://dev.scriptics.com) . 

Button 
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Clickable buttons are probably the most widely used widget in any interface, and 
Tkinter has a many options available for button components; these are listed in Table 
4.6. 


Table 4.6. Button Properties 


Property 

activebackground 
activeforeground 
bitmap 
default 

disabiedforeground 

image 
state 
takefocus 
text 

underline 

wraplength 


Function 

Sets the background eoior 
Sets the foreground eoior 
Displays a given bitmap as the button 
Identifies the default button 

Sets a foreground eoior used when button is disabled (grayed 
out) 

Sets an image to display in the widget (precedes bitmap) 

Defmes the button state (as normal, active, or disabled) 

Indieates whether the Tab key ean be used to reaeh this button 

Delines the text to display within the button 

An offset applied on text displayed to identify which eharaeter 
must be underlined 

Determines distanee when text should be wrapped to the next 
line 


Buttons also have their own speeial methods: f lash () is a method whieh reverses and 
resets the foreground and baekground attributes, and invoke () is a method that 
executes the function defined in a command. 

I used a button widget in the last chaptefs GUI sample, inititated by the following code 
and looking like Figure 4.8 (a short Hello_Button.py sample is also given in this 
chaptefs code section on the CD): 


Button(window, text='Exit', cominand=window.quit).pack(side=BOTTOM) 


This ean be broken down into basic components. Button () is used to create the button, 
and the parameters placed within the Button () parentheses, (window, text=' Exit', 
command=win dow. quit), dcfinc what the button can do. The pack () method extends 
Button () and defmes where the button should be placed within the window, in this 
case side=BOTTOM. 


Canvas 

The Canvas widget component is used to draw everything from ares to bitmaps to 
polygons. It is used as a way to customize graphical items, and resembles an artisf s 
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blank canvas, ready to be painted. A canvas in Tkinter, of course, has its own 
properties; these are listed in Table 4.7. 

Hello_Canvas .py is given on the CD as a sample that produces a large widget surface, 
as shown in Figure 4.10. 

Figure 4.10. Sample Canvas widget 



Figure 4.9. The widget at work 



Tabie 4.7. Canvas Properties 


Property 

arc 

bitmap 

image 

line 

oval 

polygon 


Function 

Creates an arc or an arc item 
Creates a bitmap item 
Creates an image item 
Creates a line item 

Creates a circle or ellipse at the given coordinates 

Creates a polygon item (three or more vertices) with the given coordinates 
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Table 4.7. Canvas Properties 


Property Function 

rectangle Creates a rectangle item with the given coordinates 

text Creates a text item at the given position with the given options 

window Embeds a window widget to the canvas 


Checkbutton 

A Cheekbutton is basieally a box that ean either be ehecked or unchecked; an example 
is shown in Figure 4.11 and a sample is included in the CD's source code as 
Hello_Checkbutton.py. Checkbuttons can have an on value and an off value set for 
whether the box is ehecked, and have a handful of methods available, as shown in Table 

4.8. 


Figure 4.11. A sample checkbutton 



Table 4.8. Checkbutton Methods 

Method Function 

seiect () Selects the checkbutton and sets the value of the variable to onvaiue 
f lash () Reverses and resets the foreground/background colors 

invoke () Exccutcs a function defined by command () 
toggle () Revcrscs the state of a button (i.e. off becomes on) 

Entry 

The Entry widget is designed to let users enter a single line of text within a frame or 
window. A sample Hello_Entry .py is included on the CD. 
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Frame 


A Frame widget is used to group, arrange, and organize other widgets. It uses 
rectangular screen areas and padding to put them into view for a GUI. A sample 
Hello_Frame .py is included on the CD. 


Label 

A Label widget is a box that displays text or images. The Label widget allows you to 
create and update these displays, and a demonstration is given as Hello_Label .py on 
the CD. 

Listbox 

A Listbox widget creates lists of text items that can be selected by the user. Listboxes 
have three properties: 

• height, The number of rows in the list. Setting height to 0 allows listbox to 
automatically resize to the number of entries. 

• selectmode. Detines the type of list being created. This can be single, 

EXTENDED, MULTIPLE, Or BROWSE. 

• width, The Number of characters in each row, which can also be automatically 
resized with the setting 0. 

The Listbox widget also has a number of methods associated with it, as shown in Table 

4.9. 


Table 4.9. Listbox Methods 


Method 

delete () 
get () 
insert () 
see () 

select_clear() 
select set () 


Function 

Deletes a given row, or the rows between the given row and lastrow 

Gets the string that starts at the given row 

Inserts the given string at the given row 

Makes the row visible to the user 

Clears the selection 

Selects the rows starting at startrow and ending at endrow 


A Listbox example is on the CD as Hello_Listbox.py. 

Menu 

There are three types of Menu widgets: pop-up, toplevel, and pull-down. There are also 
special menu widget item types such as radio menu items and check menu items. A 
sample menu is given as Hello_Menu.py. Menus, of course, have their own methods, as 
listed in Table 4.10: 
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Table 4.10. Menu Methods 


Methods 

Function 

add command() 

Adds a menu item 

add radiobutton() 

Creates a radio button menu item 

add checkbutton() 

Creates a eheek button menu item 

add Cascade 0 

Creates a new hierarehieal menu 

add separator 0 

Adds a separator line to the menu 

add () 

Adds a speeified type of menu item 

delete () 

Deletes the menu items firom startindex to endindex 

entryconfig() 

Modifies a menu item 

index() 

Returns the index number to the given menu item 


These methods have their very own options available to them, as shown in Table 4.11. 

Menubutton 

Menubuttons can be used to display menus, but are in deeline since the Menu widget 
has been expanded to inelude most of the Menubutton funetionality. 

Message 

Message is very similar to the Label widget, and is used to ereate a multiple line non - 
edi table objeet that displays text. 

Radiobutton 

Radio button widgets are multiple-ehoiee buttons. Eaeh group of radio buttons must be 
assoeiated to the same variable, and eaeh Radiobutton must represent a single value at 
any given time. Radiobuttons have their own properties: 

• command. Function to be called when the button is clicked. 

• variable. Variable to updated when button is elieked. 

• value. Delines the value that is stored in the variable when button is elieked. 


Table 4.11. Menu Widget Method Options 


Option 

accelerator 

command 

indicatorOn 


Function 

A keyboard altemative to a menu option 

Names the callback funetion when the menu item is selected 

Adds a switeh next to the menu options 
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Table 4.11. Menu Widget Method Options 


Function 

Defines the text of the menu items 
Switches color (with indicatorOn) 

Defines menu item status (normal, active, or disabled) 

Values to be stored in the variable property 
Values to be stored in the variable property 
Creates a clickable separator at the top of the menu 
Defines the index position of the character to be underlined 
Variable used to store a value 

Radiobuttons also have their own special methods: 

• flash(), Reverses forground and background colors. 

• invokeQ. Executes command function. 

• select(), Selects the radio button. 

A Radiobutton is shown in Figure 4.12 and a sample is included in the CD samples 

Hello_Radiobutton.py. 


Figure 4.12. A radio button 



Option 

label 

selectColor 

state 

onvalue 

offvalue 

tearOff 

underline 

variable 


Scaie 

A scaie widget is a graphical slider object that allows a user to select values from a 
scaie. Scaie has its own unique methods: 

• get(), Gets the current scaie value. 

• set(), Sets the scaie to a specified value. 




Hello_Scale .py is included on the CD as a sample and Figure 4.13 displays the output 
of the sample code. 


Figure 4.13. A ScaJe sample widget 



ScroUbar 

A scrollbar widget is used to select from a vertieal seroller and works with listbox, 
text, and canvas. Serollbar in Tkinter has the same methods available as scale: 

• set(), Defines fractions between 0 and 1 that delimit the view. 

• get(), Retums the current scrollbar configuration settings. 

A sample scrollbar is incuded on the CD (Hello_Scrollbar) and also illustrated in 
Figure 4.14. 


Figure 4.14. A scale sample widget 



Text 

Text allows the editing and formatting of multiple lines of text and has a number of 
available methods, as listed in Table 4.12. 
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Table 4.12. Text Methods 


Method 

Function 

delete () 

Deletes specilied character(s) 

get () 

Retums speeific character(s) 

index() 

Retums absolute value of an index 

insert() 

Inserts string at a speeified index 

see () 

Retums tme if the text located at a given index is visible 


There are also a few available attributes for text: 

• state. Sets text to editable or non-editable with the flags normai or disabied. 

• tabs. Provides a list of strings and identifies table stops on the Text widget. 

Text widgets support bookmark positions, ealled Marks; the naming of regions of texts, 
called Tabs; and speeific loeations, ealled Indexes, to help them organize text. Eaeh of 
these three—Marks, Tabs, and Loeations—has aecess to speeified methods. 

Toplevel 

The Toplevel widgets are directly managed by the window manager; its methods are 
listed in Table 4.13. 

Universal Widget Methods 

AU widgets in Tkinter also have Standard universal options for defining things they have 
in common. They all use a similar syntax, and are listed in Table 4.14. 

There are also methods inherited firom the base Tk classes that are provided for all 
Tkinter widgets, including the toplevel object created by the Tk ( ) method. These 
always apply to the widget that makes the method call, and are listed in Table 4.15. 

Take notice of the idea of focus with these methods. The window or widget that is in 
focus is the one that is toplevel to the viewer. 

Table 4.13. Toplevel Methods 
Method Function 

aspect () Controls the relation between height and width 

Client () Used in X Windows to defme wm_client_machine 

colormapwindows () Uscd in X wlndowS tO dcfinc WM_COLORMAP_WINDOWS 

command () Jn X dcfincs WM_COMMAND 

deiconifyO Dlsplays the wlndow 
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Table4.13. Toplevel Methods 


Method 

frame() 
focusmodel() 
geopmetry() 
group() 
iconbitmap() 
iconify() 
iconmask() 
iconname() 
iconposition() 

iconwindow() 
maxsize () 
minsize() 

overrideredirect() 

positionfrom() 
protocol () 
resizable () 
sizefrom() 
state () 

title () 
transient() 

withdrawn() 


Function 

Returns the window identifier 

Sets the focus model 

Changes the window's geometry 

Adds given window to the window group 

Detines a bitmap for when the window is iconified 

Turns the window into an icon 

Detines an icon bitmap for when the window is iconified 

Defines an icon name for when the window is iconified 

Defines a suggestion for where the icon goes when the window 
is iconified 

Defines the icon window that should be used as an icon 

Defines the maximum size for the window 

Defines the minimum size for the window 

Defines a flag different from 0, and telis the window manager 
not to add a title or borders to the window 

Defines the position controller 

Registers a function with a callback 

Defines resize fiags 

Defines size controller 

Returns the current state of the window, being normal, iconic, 
withdrawn, or icon 

Defines the window title 

Turns window into a temporary window for the given master 
which is automatically hidden 

Removes the window from the screen 


Table 4.14. Standard Tkinter Widget Options 

Standard Widget Properties 

Option 


height 

width 

background or bg 
foreground or fg 


Defines height in number of characters or pixels 
Defines width in pixels or number of characters 
Defines background color 
Defines foreground color 
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Table 4.14. Standard Tkinter Widget Options 


Standard Widget 
Option 

relief 

highlightcolor 

highlightbackground 

highlightthickness 
borderwidth or bd 
text 

j ustify 
f ont 

command 

variable 

anchor 

padx 

pady 

cursor 


Properties 

Defines border style 

Defines color used to draw the highlight region when widget 
has keyboard focus 

Defines color used to draw the highlight region when widget 
does not have keyboard focus 

Defines highlight region width in pixels 

Width of widget relief border in pixels 

Contains widget caption text, formatted by foreground and 
font 

Sets LEFT, RiGHT, or CENTER for tcxt captions 

Can define font family, font size, and font values like bold, 
underline, and overstrike 

Associates a widget with a Python function 

Maps widget to a variable 

Defines location of a widget within a window or of text 
within a widget 

Defines padding on the x-axis to border 
Defines the padding on the y-axis to border 
Defines mouse pointer when moved over widget 


NOTE 

CAUTION 

Colors can vary from platform to platform. For instance, the Windows operating system 
has System color settings for Windows in the Control Panel, while the UNIX X Window 
System keeps them in an xrgb text file. This could cause GUI color choices to change 
slightly (or radically) from one operating system to the next. 


Method 

eget() 


config() 
configure() 


Table 4.15. Tkinter Widget Methods 
Function 

Returns a string that contains the current configuration value for 
a given option 

Sets the values for one or more options 
Same as conf ig () 
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Method 

destroy() 
focus () 


Table 4.15. Tkinter Widget Methods 
Function 

Destroys the widget 
Sets the widget to a keyboard focus 

focus_set() As focus 0 

focus_display ( ) Returns the name of the window that contains the widget and 

has focus 

f ocus_f orce () Givcs kcyboard focus to the widget 

f ocus_get () Returns the identity of the window that has focus 

focus_lastfor () Returns the window that last had focus 
getvar () Returns the value of a Tkinter variable 

grab_set () Grabs all events for the entire screen for the widget 

g r ab_r e 1 e a s e ( ) Relcascs grab on a widget 

grab_set_global () Returns none, local, or global dcpcnding upon the grab value 

set to a window 

keys () Returns all options available for a widget as a tuple 

lift () Moves a widget to the top of the window stack 

tkraiseO Same as lift ( ) 

lower () Moves a widget to the bottom of the Windows stack 

ma 1 n 1 o op () ActivatCS thc ma i n 1 o op CVCnt 

1 1 () Quits the ma i n l o op cvcnt 

setvar () Scts a valuc to a given Tkinter variable 

update () Processes all queued tasks 

update_idletasks () Proccsscs all pcnding idlc tasks 

tk_focusNext () Returns the next widget that should have keyboard focus 

tk_focusPrev () Returns the previous widget that should have keyboard focus 

wait_variable () Creatcs a local cvcnt that waits for the given Tkinter variable to 

change 

wait_visibiiity () Crcatcs a local cvcnt that waits for the given widget to become 

visible 

wait_window () Crcatcs a local event that waits for a given widget to be 

destroyed 

There are also specific methods for all widgets that work within Windows. For case of 
reference, they begin with a winf o (short for Window Information). These methods are 
listed in Table 4.16. 
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Table 4.16. 

Method 

winfo cells() 
winfo_children() 
winfo class() 
winfo_colormapfull() 
winfor containingO 

winfo_depth() 

winfo_exists() 

winfo_fpixels() 

winfo_geometry() 
winfo_height() 
winfo width() 
winfo_id() 
winfo ismappedO 
winfo managerO 
winfo_name() 
winfo parento 
winfo pathname() 
winfo pixels() 

winfo pointerxO 

winfo pointeryO 

winfo_reqheight() 

winfo_reqwidth() 
winfo_rootx() 

winfo_rooty() 


Widget Window Information Methods 
Function 

Returns the number of cells in the widgets color map 

Returns a list of widget instances 

Returns the Tkinter class name for widget 

Returns true if a widget's colormap is full 

Returns the identity of the widget at the given x + y 
coordinates 

Returns bit depth of the widget (8, 16, 24, or 32 bits per 
pixel) 

Returns true if a Tk window corresponds to the given 
widget 

Returns the resuit of the conversion of the given distance to 
the corresponding number of pixels (in floating point 
value) 

Returns a string showing the widget coordination in pixels 
Returns pixel height 
Returns pixel width 
Returns window identity 

Returns true if a widget is mapped by the window System 

Returns the name of the geometry manager 

Returns widget name 

Returns widget parent 

Returns pathname of widget 

Same as winfo_fpixels () except returns a regular integer 
instead of a floating point value 

Returns the x coordinate of the mouse pointer in pixels 
(must be in widget window) 

Returns the y coordinate of the mouse pointer in pixels 
(must be in widget window) 

Returns minimum height required by widget to be 
displayed 

Returns minimum width required by widget to be displayed 

Returns the pixel coordinates of a widget's upper-left 
comer 

Returns the pixel coordinates of a widget's upper-left 
comer 
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Table 4.16. Widget Window Information Methods 


Method 

winfo screen() 
winfo_screencells() 

winfo_screendepth() 
winfo screenheight() 
winfor screenwidth() 
winfo_screenmmheight() 
winfo screenmmwidth() 
winfo_screenvisual() 

winfo_toplevel() 

winfo_visual() 

winfo X() 

winfo y() 


Function 

Returns the screen name for the eurrent window 

Returns the number of cells in the default eoior map for 
widget's sereen 

Returns the bit depth of the window target 

Returns the height of a widget sereen in pixels 

Returns width of widget sereen in pixels 

Returns sereen height but in millimeters 

Returns sereen width but in millimeters 

Returns the default visual class used for widget's sereen 
(i.e. grayscale, trueeolor, statieeolor, and so on) 

Returns the widget instance of the top-level window 
containing the widget 

Returns the visual elass used for the widget (grayscale, 
trueeolor, statieeolor, etc.) 

Returns x axis pixel eoordinates eorresponding to the 
widget's upper-left eorner, relative to upper-left eorner of 
the parent 

Returns y axis pixel eoordinates eorresponding to the 
widget's upper-left eorner, relative to upper-left eorner of 
parent 


Tkinter Geometry 

Tkinter widgets have speeifie geometry management methods that are used to organize 
widgets in their area. These methods are organized in three elasses that help a UI 
designer develop an interfaee. The methods are pack (), grid (), and place (). 

Using these methods is fairly effortless. First you ereate a widget. In the last ehapter you 
ereated a widget firame ealled window: 


Import Tkinter * 
window = frameO 


After you have a widget, you ean simply and easily apply pack (), grid (), or place () 
directly on it: 


window.pack() 
window.grid() 
window.place() 


157 



Using these three methods is very important in organizing a GUI interface, so FU cover 
each one in the next subsections. 

packQ 

The pack () method is used to organize widgets in blocks before placing them in the 
parent widget. pack () adds a widget to a frame or window based on the order that the 
widgets are paeked. If you don't speeify how the widgets are to be paeked, they are 
simply plaeed top to bottom in the available spaee. You can, however, speeify 
plaeement with options like anchor or side. The pack () method has a few built-in 
methods, shown in Table 4.17. 


Table 4.17. pack o Method Options 


Option 

Expand 

Fili 

Ipadx 

Ipady 

Padx 

Pady 

Side 


Use 

Expands a widget to use up available spaee 
Delines how a widget should fili a pareel or frame 
Used with f iii to define spaee in pixels around an objeet 
Used with f iii to define spaee in pixels around an objeet 
Defines spaee in pixels between widgets 
Defines spaee in pixels between widgets 

Defines where you want to place the widget (chosen from top, bottom, left, 
and right) 


NOTE 

TIP 

The default is to use pixels to define measurement in pack (), but you can define 
different measurements, such as onscreen centimeters (c), onscreen millimeters (m), 
inches (i), and printer points (p). You speeify which measurement to use by adding the 
letters to the options measurements: 


# this specifies padding to be in inches 
window.pack(padx=4i, pady=5y) 


gridO 

The grid () mcthod is used to organize widgets via a table within the parent widget. 
grid () creates a grid pattern (go figure) within a frame, and then allocates spaee to 
each cell in the grid to hold a widget. This grid starts are location (0,0) at the top left of 
the window. Grid () has a few methods, outlined in Table 4.18. 
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Table 4.18. grido Method Options 


Option 

Column 

Columnspan 

Row 

Rowspan 


Use Example 

Specifies the column number 

To make a widget span multiple (default is 1 column) 
Specifies the row number 

To make a widget span multiple rows (default is one row) 


placeQ 

The place () method is used to plaee widgets in speeific a speeific position in the 
parent widget. place () allows you to set the exact position and size of eaeh widget, in 
terms of absolute or relative coordinates. The place () method ean use the options 
listed in Table 4.19. 


Table 4.19. pia ce () Method Options 


Option 

Anchor 

Bordermode 

Height 

In 

Relheight 

Relwidth 

Rely 

Relx 

Width 

Y 

X 


use 

Defmes coordinates by (by compass: n, s, e, w, ne, nw, se, sw, or 
center). Default value is nw 

Defmes inside or outside 

Detines widget height in pixels 

Plaees widget in a position relative to the given widget (in ) 
Detines relative height in reference to in_ 

Detines relative width in reference to in_ 

Detines relative position in, reference to in_ 

Detines relative position in reference to in_ 

Defmes widget width in pixels 

Defme absolute position of widget on y-axis, default 0 

Defme absolute position of widget on x-axis, default 0 


Tkinter Events 

Events in Tkinter are user events like keyboard presses and mouse movements. Tkinter 
handles events by ereating bindings for specitic objects. You can bind events to a 
widget, to the widgefs Toplevel window, to a widgefs class, or to an entire applieation. 

Once an event has been bound to a widget, you speeify a callback, which is a function 
that is ealled when the event happens. Lefs say you had a function called My_Event: 
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def My Event () : 

//does something here 


Let's say you want My_Event to be called by a widget button called My_Button: 
My_Button = Button () 


The My_Button widget can call My_Event by simply including a command option on 
one line: 

My Button['command'] = My Event 


You ean assign events to keyboards and mouse presses as well, as shown in Table 4.20 
and Table 4.21. 


Event 

<Button -1> 

<Button -2> 

<Button -3> 

<B1 -Motion> 
<ButtonRelease -1> 
<Double - Button - 
<Enter> 

<Leave> 


Table 4.20. Tkinter Mouse Events 
Effect 

Mouse button (left) is pressed over widget 
Mouse button (middle) is pressed over widget 
Mouse button (right) is pressed over widget 
Mouse is moved with the button held down (dragged) 
Mouse button is released 
A double click 
Mouse pointer enters widget 
Mouse pointer leaves widget 


Event 

<Alt -x> 
<Control -X> 
<Escape> 
<key> 
<Return> 
<Shift -X> 


Table 4.21. Tkinter Keyboard Events 
Effect 

Pressed Alt and another key 
Pressed Ctrl and another key 
Pressed the Esc key 

Press any key (carries the character pressed via a callback) 
Pressed the Enter key 
Pressed Shift and another key 


The object that originated the callback exposes the attributes for events. These attributes 
are listed in Table 4.22. 
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Table 4.22. TkinterEventAttributes 


Object 

Char 

Height 

Keycode 

Keysym 

Num 

Type 

Widget 

Width 

X 

X_root 

Y 

Y root 


Attribute 

Character code of pressed key 
New height of a widget in pixels 
Key code of a pressed key 
Key Symbol of a pressed key 

The mouse button number assoeiated with an event (usually 1, 2, or 3) 

The event type 

The widget instanee 

New width of a widget in pixels 

The current position in pixels of the mouse on the x-axis 

The current x-axis position of the mouse in pixels relative to the upper-left 
eomer of the screen 

The current position in pixels of the mouse on the y-axis 

The eurrent y-axis position of the mouse in pixels relative to the upper-left 
eomer of the sereen 


NOTE 

TIP 

For Tkinter mouse events, you will often find <Button -l > replaced with 
<ButtonPress-l> or <l>, all of whieh are correet syntactically. These changes work 
for the middle and right-side buttons as well. 

For Tkinter keyboard events, most keys ean be represented by plaeing them within less 
than and greater than symbols (<fi>, <Cancel>, and <End>, for example). 

There are also methods used to handle a callback by binding a Python funetion or 
method to an action that can be applied to a widget. These are shown in Table 4.23. 


Table 4.23. Tkinter Event Callbacks 


Method 

after() 

after_cancel() 
after_idle() 
bindtags() 
bind() 


Event 

Alarm eallbaek ealled after given time in milliseeonds 

Cancels an alarm callback 

When the System is idle, registers a callback 

Returns the search order used by widget 

Detines the callback that must be assoeiated to a given event 
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Table 4.23. Tkinter Event Callbacks 


Method 

Event 

bind all() 

Delines the callback that must be associated to a given event at the 
application level 

bind class() 

Delines the callback that must be associated to a given event at the 
given widget class 

<Configure> 

Widget is resized or moved to a new location 

unbind() 

Removes bindings for the given event 

unbind all() 

Removes bindings at the application level 

unbind class (i 

• Removes bindings for the given event at the given widget class 


Finally, Tkinter has protocols to handle events that communicate between the window 
manager and the GUI. This allows an application to intercept messages from the System 
and act accordingly. These protocols were original established for the X system, but Tk 
can handle events on multiple platforms. The syntax to bind a protocol to a handle event 
is as follows: 

widget.protocol(protocol, handler) 


In order for the widget to intercept a system message it needs to be on the Toplevel. The 
handler is almost always a function. 

Tkinter Images 

Tkinter uses the image class as a foundation to display graphio objects. Graphio objects 
Tkinter can display include both bitmap (Bitmapimage) and GIF (photoimage) images. 
The functions image_names and image_types are USod to handle all the images within 
the image class. The first retums a hst contammg the names of all available images, and 
the second returns a list that contains all the existing typos that were created. 

Images, once created, provide a handful of methods: image. width (), image. type (), 
and image . height () . 

Bitmapimage 

Bitmapimage is usod to display bitmap images on widgets. In Tkinter, however, a 
bitmap not a .bmp format image. Bitmaps are actually two color images (well, two 
colors and a transparency mask to be precise) and have the options listed in Table 4.24. 


Method 


Tabie 4.24. b± tmapimage Options 
Purpose 
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Table 4.24. b± tmapimage Options 


Method 

Purpose 

eget () 

Retums value of the given option 

config() 

Changes image options 

configure() 

Changes image options 

height () 

Retums height in pixels 

width() 

Retums width in pixels 

type() 

Retums the bitmap string 


These options have methods available to them, listed in Table 4.25. 

Table 4.25. b± tmapimage Optiott Methods 

Used For 

Background color 
String to be used instead of a fde 
File to be read 
Foreground color to be used 
Specifies the fde handler to be used 
String that defines the contents of the mask 
Specifies mask file 
Gives image dimensions 
Gives image dimensions 

Photoimage 

Photo Image is used for displaying full color images; it supports GIF and PPM files and 
has attributes as listed in Table 4.26. 

Table 4.26. Photoimage Attributes 
Holds 

String to be used instead of a file 
File to be read 
Dimensions 
Dimensions 


Attribute 

data 

file 

height 

width 


Method 

background 

data 

file 

foreground 

format 

maskdata 

maskfile 

height 

width 


163 



The PyOpenGL Library 

PyOpenGL is an OpenGL widget written by a large group of developers, including 
David Ascher, Mike Hartshorn, Jim Hugunin, and Tom Schwaller. PyOpenGL includes 
OpenGL bindings for Python created using the Simplilred Wrapper and Interface 
Generator (SWIG) and distributed under open source licenses. It supports OpenGL 
vl.O, OpenGL vl.l, GLU, GLUT v3.7, GLE 3, WGL 4, and Togl (Tk OpenGL widget). 
PyOpenGL is also interoperable with Tkinter, wxPython, FxPy, PyGame, and Qt and a 
large number of other extemal GUI libraries for Python. It has a very active following 
and a regularly updated sourceforge project page at http://pvopengl.sourceforge.net/ . 

OpenGL has the reputation of being difficult to leam. Hey, there are reasons why they 
pay game developers the big bucks! Python's version of OpenGL is no different than 
any other version, and OpenGL looks pretty similar no matter what language you're 
playing with. 

The reason OpenGL is considered difficult to pick up is because three-dimensional 
graphics programming can be a fairly difficult subject just on its own. Since OpenGL is 
fairly difficult to master, this section covers just a few examples. If you discover, as 
many programmers do, that OpenGL is your calling, then I recommend that you pick up 
OpenGL Game Programming by Kevin Hawkins and Dave Astle. 

Using OpenGL in Python is quite an advantage over other languages, however, because 
Python and Pygame make several complex steps much easier. For instance, I use the 
python.game window in these examples to open up a window for displaying graphics. 
This could take dozens of lines of code in a non-high-level language, but it only takes 
two in these examples. You also do not have to worry about freeing and releasing 
memory for all of the complex graphics calls and routines. However, having no control 
over memory allocation and de-allocation can cause problems. 

NOTE 

OpenGL 

OpenGL is a Standard graphics library originally created by Silicon Graphics. Back then 
it was called GPL, and only ran on SGI hardware. SGI eventually tumed their 
technology into an open Standard and licensed it to different machines. OpenGL may be 
the premier development tool for developing portable 2d and 3d applications, and it has 
also been a Standard since the early 1990s. 

OpenGL is firce for application and game designers. It is an owned technology, but the 
licensing applies to venders of hardware (i.e., the graphic card makers) that wish to 
utilize the technology, not the Software developers. SGI is currently working towards 
modifying the license into a tme open source license. This makes OpenGL very popular 
among game developers, and many commercial games have used it, firom Activision's 
Quake, to Blizzard's Diablo, to Bioware's NeverWinter Nights. 

Installing PyOpenGL 
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PyOpenGL needs a handful of dependencies in order to access all of its functionality. 
Luckily, most of these will already be installed if youVe been playing with the code in 
this chapter. PyOpenGL needs Python 2.2 or higher, Tel/Tk, OpenGL, GLU (which 
should come pre-installed on most modern machines and with most modem graphics 
card), the OpenGL Utility Toolkit (or GLUT for short), and Numerio Python. 

The OpenGL Context may also require a few dependencies, depending on the platform. 
Those dependencies that are freely distributable are on this book's CD, under 
\PYTHON\PYOPENGL\DEPENDENCIES, except for Numerio Python, which has its 
own folder (\PYTHON\NUMERIC PYTHON). The Standard binary installers for 
PyOpenGL are located on the CD under \PYTHON\PUOPENGL. The source and 
project page for PyOpenGL can be found at Sourceforge, which is where you will want 
to look for the latest updates and news: 

http://pvopengl.sourceforge.net/documentation/installation.html 

Using PyOpenGL 

There are four libraries to PyOpenGL, each of which is normally imported separately: 

• GL, The basic, primitive library. 

• GLU, Short for GL Utilities; includes more advanced commands than GL. 

. GLX. GL for X Windows. 

• GLUT, GL Utilities Toolkit, which has even more sophisticated windowing 
features. 

Eor these samples you will be using both GL and GLU: 

from OpenGL.GL import * 
from OpenGL.GLU import * 


To make things easier, you will also be using bits of the Pygame library: 

import pygame 

from pygame.locals import * 


Eirst a small program creates a PyOpenGL Window with a graphio on a Win32 
platform. This first program, labeled OpenGL_l. py in this chaptefs code section on the 
CD, also sets the procedent for each PyOpenGL example that follows, so pay attentioni 

Presenting a Window in PyOpenGL 

If you look at the sample code, the first thing you do after giving Python and Pygame 
access to the PyOpenGL libraries through import statements is to declare a couple of 
variables, Itke so: 

rquad = 0.0 

xrot = yrot = zrot = 0.0 
textures = [0,0] 
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These are variables you'll use in later examples, not for this first simple one, so you ean 
ignore them for now. 

After the variables you deflne how to size the window or PyOpenGL seene. Do this by 
ereating a windowsize funetion. This function will be ealled to set up the window or 
seene at least onee when the program is first run, and when it is ealled, it will be given 
the height and width you want the window to be: 

def windowresize((width, height)): 
glViewport(0, 0, width, height) 
glMatrixMode(GL_PROJECTION) 
glLoadldentity() 

gluPerspective(45, 1.0*width/height, 0.1, 100.0) 
glMatrixMode(GL_MODELVIEW) 
glLoadldentity() 


The first eommand in windowresize is giviewport. This eommand resets the eurrent 
view. 

The glMatrixMode (gl_projection) Une then sets up the projeetion matrix, whieh is 
responsible for adding perspeetive. glMatrixMode is defmed by the next two 
eommands, in whieh the seene is set and the perspeetive is defined. The eommand that 
follows is glLoadldentity (), whioh resets and restores the projeetion matrix to its 
original state. 

Objeets on the screen that are meant to be far away need to appear smaller in order to 
ereate realistie 3D, so the perspeetive is then defined with gluPerspective. In this 
example, the perspeetive is ealeulated by a 45-degree viewing angle based on 1 times 
(1.0*) windowsize's height and width. 0.1 and 100.0 are the starting and ending points 
for how deep the sereen ean go, and how many layers the sereen ean have. 

Finally, you use glLoadldentity () a seeond time to turn attention to the projeetion 
matrix and reset it. 

Initializing PyOpenGL 

After defining a three-dimensional window, you ean then ereate a funetion that 
initializes PyOpenGL. You need to establish what eoior the screen starts out as, the 
depth buffer, and whether to use smooth shading, as well as a number of other possible 
PyOpenGL features. Do this with an initialize eommand: 

def initialize 0 : 

glShadeModel(GL_SMOOTH) 
glClearColor(0.0, 0.0, 0.0, 0.0) 
glClearDepth(1.0) 
glEnable(GL_DEPTH_TEST) 
glDepthFunc(GL_LEQUAL) 

glHint(GL_PERSPECTIVE_CORRECTION_HINT, GL_NICEST) 
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In initialize, yOU USG glShadeModel (GL_SMOOTH) first to ask PyOpenGL to USG 
smooth shading (smooth shading is simply one way of blending colors and lighting 
when rendering a polygon). Next you use glciearColor, which sets the color of the 
window screen when it is ciear. 

PyOpenGL takes in four numbers when you declare a color. The first three represent the 
primary colors red, green, and blue, and the last is the alpha (transparency channel). 
Each number can range from 0.0 to 1.0; the lower the number, the darker the intensity, 
the higher the number, the brighter the intensity. The numbers must be in order of Red, 
Green, Blue, and Alpha. You can create different colors by mixing these primary colors. 
Black would be (0,0,0,0), white would be (1,1,1,0), and yellow would be (1,1,0,0). Of 
course, the last number is the alpha or transparency. 

After setting the screen color you set up the depth buffer. The depth buffer keeps track 
of how many layers deep the screen goes, and you need to have depth in order to ha ve 
any sort of 3D. The depth buffer actually keeps track of which objects are in front and 
which are in back, so it knows how to draw the screen in the proper perspective. There 
are three commands associated with the depth buffer in our initialize function: 
glClearDepth, glEnable, and glDepthFunc. 


giciearDepth specifies thc dcpth valuc used when the depth buffer is cleared. The 
glEnable command is used to enable various PyOpenGL capabilities. In this case, it is 
enabling depth testing, which will allow initialize to do depth comparisons and 
update the depth buffer. glDepthFunc specifies the function used to compare each 
incoming pixel depth value with the depth value present in the depth buffer. LEQUAL 
is short for Eess than or Equal to, and sets glDepthFunc to pass the incoming depth 
value if it is less than or equal to the present value. 

giHint (GL_PERSPECTivE_coRRECTiON_HiNT, gl_nicest) is a long command, but ifs 
basically only a way of telling PyOpenGE to please use the best corrective perspective 
and the highest-quality view when there is room for interpretation. 

Drawing a Square 

Our third function is the code that actually draws the display, so lef s call it 
drawgraphics ( ). This function will actually display everything that goes onto the 
screen, so it will be doing most of the work in each example. 

def drawgraphics () : 

glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT) 

glLoadldentity() 

glTranslatef(0.0, 0.0, -5.0) 

glBegin(GL_QUADS) 

glVertexSf(-1.0, 1.0, 0) 

glVertexSf(1.0, 1.0, 0) 

glVertexSf(1.0, -1.0, 0) 

glVertexSf(-1.0, -1.0, 0) 

glEnd() 
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First you giciear to clear the screen to a color, ciear the buffer, and then reset with 
glLoadidentity. glLoadidentity actually moves you to the eenter of the sereen, 
whieh is 0,0 on the x- and y-axis. Left and down are negative numbers, and right and up 
would be positive numbers; see Figure 4.15. 

Figure 4.15. Three-dimensional space labeled byX,Y, and Z 



The glTranslatef () eommand produees a translation of the current matrix by 
multiplying it by the x, y, and z coordinates given to it. This sounds eonfusing, but all it 
really does is ehange the drawing point from the eurrent view to someplaee else. In this 
ease, you do not ehange the glTranslatef () x or y eoordinates (leaving them at 0,0) 
but you do give a -5.0 for the z-axis, whieh basically pushes the matrix back five sereen 
depths. If you didn't push the matrix back, what you drew would be too elose to the 
front of the 3D spaee for you to see it. Basieally, glTranslatef () is the eommand that 
moves along the X-, y-, andz-axes. For instanee, glTranslatef (1.5, 0.0, and -6.0) 
would mean to move left 1.5 units and into the screen depth by 6 units. 

NOTE 

TIP 

When you use glTranslatef (), you are not moving eoordinated relative to the eenter 
of the sereen, you are actually moving glTranslatef () relative to wherever it 
eurrently is. If you left glTranslatef () at the top right eorner of the sereen with the 
last eommand, that is where it will stili be when you use it later. This means you need 
always keep traek of its eurrent position. 
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glBegin tells PyOpenGL that you want to start drawing, and (gl_quads) telis 
PyOpenGL that you want to draw a square or four-sided shape of some sort. You use 
givertex () to teli PyOpenGL where the four points of your square shape are loeated 
on the X-, y-, and z-axes, and glEnd () means you are done drawing and that there are 
no more points. The first givertex () number is is the first point of the square (and the 
x-axis, if you are drawing a polygon). The seeond number is the y-axis, and the third 
number is the z. 

You have three usable funetions; now you just have to set them up in a main loop. 


def main () : 

# Define any variables 
video_flags = OPENGL|DOUBLEBUF 

# Initialize Pygame 
pygame.init() 

pygame.display.set_mode((640,480), video_flags) 

# Call our windowsize and Initialize funetions 
windowsize((640,480)) 

initialize () 

#set frames to 0 before loop starts 
frames = 0 

# Have pygame keep track of time 
ticks = pygame.time.get_ticks() 

# while loop that draws and looks to quit 
while 1: 

event = pygame.event.poli() 

if event.type == QUIT or (event.type == KEYDOWN and event.key 
== K_ESCAPE): 

break 

# Draw our fun graphies 
drawgraphics () 
pygame.display.flip() 
frames = frames+1 

if name == ' main ': main() 


There is aetually quite a bit going on here. First, you define video_f lags to be 
OpenGL and double-buffered; these are ealls you need to make to Pygame in order to 
render OpenGL correetly. Then you initialize Pygame with its inito method and set 
the display to 640x480 with your video flags. 

NOTE 

Double Buffering 

Drawing and redrawing sereens and images ean be time- and proeessor-eonsuming, and 
game programmers have developed many trieks for inereasing the speed it takes to 
render drawings. One of these trieks is called double buffering, and is very eommon 
when animating. Double buffering is so eommon, in fact, that most modem game and 
animation libraries have built-in support for flags for using the teehnique. Can you 
believe that programmers used to have to ereate their own buffers by hand? Talk about 
Dark Ages! 
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Normally, when an image is redrawn, it is simply redrawn in place on the screen. In 
double buffering, the image is redrawn ahead of time in a buffer or a hidden area of the 
sereen or memory, and then, when it is time to re-display, the buffer is simply eopied to 
the sereen. In reality, a complex animation or sequenee may have dozens of unseen 
layers eonstantly loading with the graphics that will display seeonds later. 

Then you eall the windowsize function with the same display size (640x480) and the 
initialize function that initializes PyOpenGL. You set up a baseline firame variable 
(equaling 0) and then you ask Pygame to use pygame. get. ticks to keep traek of time 
in milliseconds. 

The aetual work happens in the while loop. First, use Pygame's event .poli () function 
to see, via keyboard input and an if statement, whether the user wants to quit. Then call 
the draw graphicsfunction, whieh draws the square. 


pygame . display. f lip () updates the display eaeh time it is ealled. pygame . dipsplay 
knows that you are using OpenGL and double buffering beeause of your earlier video 
flags, so it updates the entire display by swapping the current view with the new ones it 
has drawn and stored in memory (this is ealled a gl buffer swap). Then you update your 
frames so that you know how many times the while loop has looped, and finally you 
initiate main with a Standard Python if line. 

Whew! If you run OpenGL_l .py you'll see a white square open in a 640x480-pixel 
Pygame window, similar to that in Figure 4.16. 

Figure 4.16. OpenGL l.py displays a square renderedin PyOpenGL and 
dispiayed within a Pygame window 



Setting the Coior ofan Object 
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Now that you have a baseline, let's look at what else you can do with PyOpenGL. Let's 
try giving the square a color. You can use the glColorSf () command, which also takes 
in three commands, one each for red, green, and blue intensity values: glColorSf (r, 
g, b, ). PyOpenGL keeps these standards eonsistent aeross commands, so the eolors 
have a range from 0.0 to 1.0 and work exactly the same as if you were setting up the 
sereen baekground eoior with giciearCoiorSf () . 

Tuming on glColorSf is like switehing to a different-eolored pen. When you switeh to 
red, everything you draw after that point is red. Then, if you switeh to another eoior, 
everything you draw after that is drawn in the new eoior. To make your square a Python 
green, you simply need to add the glColorSf eommand in your drawgraphics () 
function before you begin drawing with glBegin (gl_quads) , like so: 

def drawgraphics () : 

glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT) 
glLoadldentity() 
glTranslatef(0.0, 0.0, -5.0) 

#Adding color to our square 
glColorSf(0.1, 0.9, 0.5) 
glBegin(GL_QUADS) 
glVertexSf(-1.0, 1.0, 0) 
glVertexSf(1.0, 1.0, 0) 
glVertexSf(1.0, -1.0, 0) 
glVertexSf(-1.0, -1.0, 0) 
glEnd() 


Now when you run this program (labeled OpenGL 2 . py on the CD), you will see a 
green square just like that in Figure 4.17. Notiee that the polygon filis in the entire 
surfaee with the eolors youVe drawn. This is ealled smooth eoloring. 

Figure 4.17. Coloringin a surfaee with gicoiorSfO 




Rotation and Movement 


Now that you can color the square, let's try to rotate it. To do so, you need to add a bit to 
the drawgraphics function. First, make use of the rquad (rquad is short for rotate 
quad) variable by declaring it a global and then calling the glRotatef () function. Use a 
variable for rotation so that you have fine-grain eontrol over the movement. 

glRotatef (angie, x, y, z) produees a rotation of a given angle in degrees over a 
given vertiees given in x, y, and z eoordinates. The command takes four arguments: 
Angle, X vector, Y vector, and Z vector. Angle is a number that represents how 
mueh to spin the objeet. The x, y, and z veetors represent the veetor around which the 
rotation will oceur. For instanee, (1,0,0), deseribes a veetor that travels in the direetion 
of 1 unit along the x-axis. 

The current matrix (remember ifs ali about glMatrixMode) is ehanged by this rotation. 
Set up the rotation by adding one line that ealls glRotate () on your square using the 
rquad Variable as the angle and rotating on the x-axis: 

def drawgraphics () : 

glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT) 
glLoadldentity() 
glTranslatef(0.0, 0.0, -5.0) 

# Set up rquad for rotation, only real difference 
global rquad 

glRotatef(rquad, 1.0, 0.0, 0.0) 

glColorSf(0.1, 0.9, 0.5) 
glBegin(GL_QUADS) 
glVertexSf(-1.0, 1.0, 0) 
glVertexSf(1.0, 1.0, 0) 
glVertexSf(1.0, -1.0, 0) 
glVertexSf(-1.0, -1.0, 0) 
glEnd() 


And then at the end of drawgraphics you update rquad so that the drawing of the 
square eontinually rotates: 

# And update rquad for movement 
rquad+= 0.1 

This ereates a rotating flat square, as illustrated in Figure 4.18 (the souree is on the CD 

as OpenGL_3.py) . 


Figure 4.18. A flat plane rotates along its x-axis 
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By playing with the rquad variable, you can change how many degrees the plane rotates 
on the x-axis. You ean make the plane spin faster or slower, backwards or forwards, by 
ehanging the values assoeiated with it. 

Moving from Flat to 3D 

You have already done most of the work for displaying three dimensions. Let's say you 
wanted to ehange your flat plane to a eube. gl_quad is aetually eapable of displaying a 
eube objeet; you just need to teli it where the other vertiees for the other five flat planes 
should go. This becomes a pixel-plotting problem; it is shown in Figure 4.19. 

Figure 4.19. A cube and points for each side are mapped out in 3D space 
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Once you know where each pixel belongs, you can feed the location to gl_quad, which 
filis in each surface for you: 

# Front Face 

glVertex3f( 1.0, 1.0,-1.0) 
glVertex3f(-1.0, 1.0,-1.0) 
glVertex3f(-1.0, 1.0, 1.0) 
glVertex3f( 1.0, 1.0, 1.0) 

# Back Face 

glVertex3f( 1.0,-1.0, 1.0) 
glVertex3f(-1.0,-1.0, 1.0) 
glVertex3f(-1.0,-1.0,-1.0) 
glVertex3f( 1.0,-1.0,-1.0) 

# Top Face 

glVertex3f( 1.0, 1.0, 1.0) 
glVertex3f(-1.0, 1.0, 1.0) 
glVertex3f(-1.0,-1.0, 1.0) 
glVertex3f( 1.0,-1.0, 1.0) 

# Bottom Face 
glVertex3f( 1.0,-1.0,-1.0) 
glVertex3f(-1.0,-1.0,-1.0) 
glVertex3f(-1.0, 1.0,-1.0) 
glVertex3f( 1.0, 1.0,-1.0) 

# Right face 

glVertex3f(-1.0, 1.0, 1.0) 
glVertex3f(-1.0, 1.0,-1.0) 
glVertex3f(-1.0,-1.0,-1.0) 
glVertex3f(-1.0,-1.0, 1.0) 

# Left Face 

glVertex3f( 1.0, 1.0,-1.0) 
glVertex3f( 1.0, 1.0, 1.0) 
glVertex3f( 1.0,-1.0, 1.0) 
glVertex3f( 1.0,-1.0,-1.0) 


Now the cube has six sides. PyOpenGL automatically draws them in a counter- 
clockwise order—the first point is top-right, the second point is bottom-right, and so on 
until completely around the given plane. The rotation is already built-in, and the 
MatrixMode automatically knows to update each side as it rotates; check out 
OpenGL_4 .py on thc CD and Figure 4.20. 

Figure 4.20. The flat plane becomes a full rotating cube 
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Let's say you wanted to speed up and twist your rotating cube around a bit more. It's 
easy to fiddle with MatrixMode, espeeially sinee youVe thought ahead and ineluded a 
number of variables with whieh to do it: 

# Now we use all of these 

# x,y, and z rots are the rotations on each axis 
xrot = yrot = zrot = 0.0 


These variables, xrot, yrot, and zrot, ean be used to rotate the cube in a new way on 
the X-, y-, and x-axes. Do so by adding a few lines to the top of drawgraphics: 

global xrot, yrot, zrot 

glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT) 
glLoadldentity() 
glTranslatef(0.0, 0.0, -5.0) 

global rquad # not used for now 
glRotatef(xrot,1.0,0.0,0.0) 
glRotatef(yrot,0.0,1.0,0.0) 
glRotatef(zrot,0.0,0.0,1.0) 


And then add a few lines to the end of drawgraphics: 

# Use XYZ to rotate - speed it up a bit 
xrot = xrot + 0.9 
yrot = yrot + 0.9 
zrot = zrot + 0.9 


This will eause your cube to rotate quieker and also spin on aother axis. 

Adding Textures 
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In your final PyOpenGL tutorial you'll open and use a local texture image instead of 
having PyOpenGL simply eoior the cube; this is illustrated in Figure 4.21. The full code 
is listed in OpenGL_5 .py in the Chapter 4 code section on the CD. 


Figure 4.21. A textured cube spins around each axis 



First you will make use of import os. A texture will then have to be loaded from 
outside of Python, and your program will need to understand how to navigate through 
different directories and pull files from its native operating system. 

You will also finally be using the texture variables you initialized early on: 


# texturas for loading the .bmp image 
texturas = [0,0] 


You will be using texturas [ ] for loading the .bmp you will be using for texture. The 
first thing you need is a new function that opens up the .bmp file: 

# New function to find, load, and use the texture 
def loadtextures(): 

# Need to find and load the texture 

point to file = os.path.join('dtcfe.bmp') 

texture surface = pygame.image.load(point to file) 

texture buffer = pygame.image.tostring(texture surface, "RGBX", 1) 

First, point_to_file uses the os module's os .path. j oin to point to the .bmp you 
want to use—in this case it is the dtcfe.bmp file found on the CD with the code samples. 
The next two commands use Pygame methods to load the .bmp image to a new surface 
(texture_surface) and then copy the image into a larger string buffer 
(texture buffer). Spccifying RGBX tells Pygame that the texture should be 32-bit 
padded RGB data. This turns the .bmp image into an actual texture. 
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With Pygame, your textures must be at least 64x64 pixels, and shouldn't be more than 
256x256 pixels. Textures need to be sized in height and width to the power of 2 (if the 
textures are 64x64, 128x128, or 256x256, they do not need to be resized, otherwise they 
do). These are of eourse the Standard defaults for textures and are ehangeable, but not 
without more advaneed programming. 

Now that Pygame has the texture, you hand it over to OpenGL. First you need to 
speeify that the texture is two-dimensional with gl_texture_2d, and then you need to 
bind it to a texture [ ] array that will hold any and all textures your program needs: 

glBindTexture(GL TEXTURE 2D, textures [0]) 


glTextimage2D is a PyOpenGL oommand that speeifies a two-dimensional texture. 
You feed it several values, ineluding the texture surfaee, width, and height (using the 
get_width ( ) and get_height () methods). Then you speeify that the texture is two- 
dimensional with GL_TEXTURE_2D, explain how the eoior format is organized with 
GL_RGBA, deline the data format used to store the texture data with gl_unsigned_byte, 
and finally, you give glTextimage2D ( ) the aetual data of the texture itself, 
texture_buf fer, whieh you defmed with Pygame: 

glTexImage2D( GL_TEXTURE_2D, 0, GL_RGBA, 
texture_surface.get_width(), texture_sur- 
face.get_height(), 0, 

GL RGBA, GL UNSIGNED BYTE, texture buffer ); 


Whew—that's our longest one-liner yet. The last step in loading a texture is to teli 
PyOpenGL what filtering to use when the image is stretehed or altered on the sereen. To 
do so, use PyOpenGL's built-in glTexParameterf (), whieh simply defmes the options 
to use when texture mapping. The min and mag filters speeify texture magnifieation, and 
GL_NEAREST asks PyOpenGL to grab the nearest pixel when redrawing the 
GL_TEXTURE_2D image: 

glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST) 
glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST) 


Now that you ean load the .bmp image and turn it into a texture, you need to make 
PyOpenGL use the texture on eaeh side of the eube instead of filling in the sides with 

glColorSf(). 

Drawing a textured cube is quite a bit different from drawing colored cubes. Most of the 
gl functions are the same but the glBindTexture command we used to load textures 
sets the texture we want to use, much like giCoiorSf () set the pen to a specific color: 

glBindTexture(GL TEXTURE 2D, textures[0]) 
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To map the texture correctly into a specific side of the texture, you need to make sure 
the top-right of the texture is mapped to the top-right of the side; same with the bottom- 
left. Eaeh eorner needs to be mapped using the giTexCoord2f (), command like so: 

glTexCoord2f(0.0, 0.0); glVertexSf(-1.0, -1.0, 1.0) 

The glTexCoord2f commaud is designed to map out textures in two dimensions. Once 
you get the hang of using the eommand it is as easy to use as glColor, there is just an 
added complexity to eaeh of the cube's mapped points: 

glBegin(GL_QUADS) 

# Front Face 

glTexCoord2f(0.0, 0.0); glVertexSf(-1.0, -1.0, 1.0) 

glTexCoord2f(1.0, 0.0); glVertexSf( 1.0, -1.0, 1.0) 

glTexCoord2f(1.0, 1.0); glVertexSf( 1.0, 1.0, 1.0) 

glTexCoord2f(0.0, 1.0); glVertexSf(-1.0, 1.0, 1.0) 

# Back Face 

glTexCoord2f(1.0, 0.0); glVertexSf(-1.0, -1.0, -1.0) 

glTexCoord2f(1.0, 1.0); glVertexSf(-1.0, 1.0, -1.0) 

glTexCoord2f(0.0, 1.0); glVertexSf( 1.0, 1.0, -1.0) 

glTexCoord2f(0.0, 0.0); glVertexSf( 1.0, -1.0, -1.0) 

# Top Face 

glTexCoord2f(0.0, 1.0); glVertexSf(-1.0, 1.0, -1.0) 

glTexCoord2f(0.0, 0.0); glVertexSf(-1.0, 1.0, 1.0) 

glTexCoord2f(1.0, 0.0); glVertexSf( 1.0, 1.0, 1.0) 

glTexCoord2f(1.0, 1.0); glVertexSf( 1.0, 1.0, -1.0) 

# Bottom Face 

glTexCoord2f(1.0, 1.0); glVertexSf(-1.0, -1.0, -1.0) 

glTexCoord2f(0.0, 1.0); glVertexSf( 1.0, -1.0, -1.0) 

glTexCoord2f(0.0, 0.0); glVertexSf( 1.0, -1.0, 1.0) 

glTexCoord2f(1.0, 0.0); glVertexSf(-1.0, -1.0, 1.0) 

# Right face 

glTexCoord2f(1.0, 0.0); glVertexSf( 1.0, -1.0, -1.0) 

glTexCoord2f(1.0, 1.0); glVertexSf( 1.0, 1.0, -1.0) 

glTexCoord2f(0.0, 1.0); glVertexSf( 1.0, 1.0, 1.0) 

glTexCoord2f(0.0, 0.0); glVertexSf( 1.0, -1.0, 1.0) 

# Left Face 

glTexCoord2f(0.0, 0.0); glVertexSf(-1.0, -1.0, -1.0) 

glTexCoord2f(1.0, 0.0); glVertexSf(-1.0, -1.0, 1.0) 

glTexCoord2f(1.0, 1.0); glVertexSf(-1.0, 1.0, 1.0) 

glTexCoord2f(0.0, 1.0); glVertexSf(-1.0, 1.0, -1.0) 

glEnd(); 


The resuit of this eode (OpenGL_5 .py) is illustrated in Figure 4.21. 
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Sound in Python 


Like with graphics, there are a number of available libraries for implementing sound in 
Python. 


• PythonWare Sound Toolkit, An (unfortunately) abandoned kit for reading and 
playing AU, VOC, and WAV fdes on Windows and Sun OSs. The unfmished 
tookit is stili available from PythonWare at http://www.pvthonware.com . 

PythonWare is a copyrighted, but free to use, library. 

• Boodler, An interesting tool for creating soundscapes which uses Python and is 
created for UNIX operating Systems (although some work on PDAs, Mac, and 
with Direct X has been done). The project can be found at 
http://www.eblong.com/zarf/boodler/ . 

Boodler combines sound samples into an ongoing stream of sound for 
background noise. 

• The Snack Toolkit, The Snack Toolkit was developed by Kare Sjolander for 
TCL and Python. It is a sound-processing toolkit with a TK interface. It supports 
MP3 and sound filtering; the idea behind the kit is rapid development. Snack 
needs both Tkinter and Tcl/Tk to work correctly. It adds the snack: sound 
command, which is used to create and handle sound objects, read audio data 
from wav fdes, and play sounds. Snack is accessed using the tkSnack module. 
You can find Information on Snack at http://www.speech.kth.se/snack . 

• The MusicKit Lihrary, MusicKit is a full, object-oriented library for signal 
Processing and building sound, music, and creating MIDI applications. The kit is 
based on Music V (From Bell Labs and Max Mathews) and was originally 
written for NeXT. These are C tools made available to Python using PyObjC or 
the Objective-C bridge. The DSP tools are only portable to Intel Systems or 
m68k, but the MIDI and sound streaming are available on Windows and Mac 
platforms (at the time of this writing the project team was stili working on a port 
to Linux). The kit can be found on its own Sourceforge page, along with on-line 
documentation, code examples, Utilities, applications, and musical scores at 
http://musickit.sourceforge.net/ . 

Python, of course, comes with a few sound functions built-in. These are included under 
Multimedia Services and listed in Table 4.27. 


Table 4.27. Python Multimedia Audio Services 

Module Use 

audioop Manipulates raw audio data.Operates on sound fragments consisting of signed 
integer samples 8, 16, or 32 bits wide, stored in Python strings 

aifc Reads and writes audio files in AIFF or AIFC format (Audio Interchange File 
Format) 

sunau An interface to the Sun AU sound format 
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Table 4.27. Python Multimedia Audio Services 

Module Use 

wave An interface to the WAV sound format. Supports stereo and mono but not 
compression and decompression 

chunk Reads EA IFF chunks 

sndhdr Provides utility functions that determine the type of a sound file 

Python also possesses a Winsound module that provides aeeess to the basie sound- 
playing maehinery on Windows platforms. Winsound ineludes a single funetion from 
the platform API, PlaySound, whieh takes in a sound parameter argument that can be 
either a filename, a string (thafs a string of audio data) or None. 

Wmsound's fiags are listed in Table 4.28. 


Table 4.28. Windsound's Fiags 

Purpose 

The sound parameter is the name of a WAV file 

The sound parameter should be interpreted as a eontrol panel sound 
assoeiation name 

Play the sound repeatedly 

The sound parameter to PlaySound () is a memory image of a WAV 
file 

Stop playing a speeified sound 
Allows sounds to play asynehronously 

If the speeified sound eannot be found, do not play the default beep 
Do not interrupt sounds eurrently playing 
Return immediately if the sound driver is busy 


Although loading and playing sounds is eovered in this seetion, audio programming and 
the seienee behind sound waves is a eomplex and in-depth field. If you fmd audio 
programming to be your bliss, I suggest eheeking out a eopy of Mason MoCuskey's 
Beginning Game Audio Programming from your loeal library. 

Playing a Sound with Pygame 

You ean play a sound using Python Pygame with just a few short lines of eode. First do 
the typieal pygame import and the os module import so that you can find files on the 
native operating system; 


Flag 

SND_FILENAME 

SND_ALIAS 

SND_LOOP 

SND_MEMORY 

SND_PURGE 
SND_ASYNC 
SND_NODEFAULT 
SND_NOSTOP 
SND NOWAIT 
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# Import necessary modules 

import os, pygame 

from pygame.locals import 


After importing the needed libraries, you initialize pygame; 

pygame.init() 


Pygame 's eross-platform musie tools for sound effeets and musie are built through the 
mixer module, so you use pygame .mixer to load the sound, and the built-in play () 
method to play it: 

soundl = pygame.mixer.Sound('JUNGLE.wav') 
soundl.play() 


Thafs it. To get this eode to run on its own (as the Play_Sound.py sample in the 
Chapter 4 eode seetion on the CD does), you also need to add a loop that keeps the 
program running so that the sound has time to be loaded and played; 

while 1: pass 


Viola! Instant sound with only six small lines of eode! Not bad at ali. Of eourse, a real 
game will need a sound function thafs a bit more versatile. 

Building a load sound Function 

A Pygame load_sound funetion would look very similar to the load_image funetion 
you ereated at the beginning of this ehapter. You start by defining the function, which 
takes in the name of the sound file: 

def load sound(name): 


The load sound code should check to see if pygame .mixer (the Pygame module that 
loads up sounds) is installed. If pygame .mixer isn't available, Pygame will not be able 
to load the sound. Pygame has a built-in feature called Nonesound, which, if used, will 
send a blank sound object if the file cannot be found, so your function will not crash 
while trying to load a non-existent sound. 

if not pygame.mixer: 

return NoneSoundO 


Next, as with ioad_image, you build the complete path to the object with the os 
module: 

fullname=os.path.j oin('data', name) 
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Then use a try/except clause and retum the sound object: 


try: 

sound=pygame.mixer.Sound(fullname) 
except pygame.error, message: 

print 'Cannot load sound:', wav 

raise SystemExit, message 
return sound 


The full snip canbe found as Load_Sound.py on the CD: 

def load_sound(name): 

class NoneSound: 

def play(self): pass 
if not pygame.mixer: 

return NoneSound() 
fullname=os.path.j oin('data', name) 
try: 

sound=pygame.mixer.Sound(fullname) 
except pygame.error, message: 

print 'Cannot load sound:', wav 
raise SystemExit, message 
return sound 
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Networking in Python 


For Python to send or receive information between two computers, it needs both of 
those computers to understand a common address. This address consists of two things: 
an Internet address (or IP address) and a port number. 

IP addresses are 32-bit numbers represented by four decimals and separated by dots (for 
example; 10.124.220.13). These numbers range firom 0 to 255. Each IP address for eaeh 
network eard or eonneetor in a network must be unique. 

A port is an entry point into an applieation or serviee that resides on the eomputer. Ports 
are numbers represented by 16-bit integers, ranging firom 0 to 65-535. Certain ports on 
any 

NOTE 

The OSI Model 

Systems of networking are defmed by the OSI/ISO (Open Systems 
Interconnection/Intemational Standards Organization) model. The OSI model is made 
up of seven layers. Most of today's networking protoeols (like TCP/IP and UDP) span a 
few of these layers. 

1. Physieal Eayer. 

Defines the information needed to transport data over physieal eomponents 
(cables). 

2. Data Eink Eayer. 

Detines how data is passed to and firom the physieal eomponents. 

3. Network Eayer. 

Organizes the network by assigning addresses to eaeh network element (IP). 

4. Transport Eayer. 

Packs data and ensures transfer on the network (TCP, UDP). 

5. Session Eayer. 

Handles eaeh individual session or eonnection made. 

6. Presentation Eayer. 

Used to handle problems with different formats and platforms. 

7. Applieation Eayer. 
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The actual applicatiori—the FTP client, HTTP browser, e-mail handlers, and so 
on, that run on the network. 

given machine are responsible for connections to certain Services and applications (for 
instance, port 80 is reserved for HTTP or Web page requests). Any number less than 
1,024 is considered privileged, or reserved, and on most computer Systems you will 
need to be an administrator of some sort to run an application on them. An example of 
this process is outlined in Figure 4.22 along with the OSI network model (see sidebar). 

Figure 4.22. Sample communication between two computer stations 
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Python uses a construet called a Socket to send and receive data between addresses. 
Sockets were originally introduced by UNIX BSD way back in the early 80s and are 
used today to provide network-application connections. Basically, each end of a 
network application needs to have a socket object of some type established on an 
address in order to send and receive data or communicate. Establishing a socket on an 
address is called binding. 

Python has a socket () module to create object-based socket-style connections, and 

Socket() 


Table4.30. socket o Methods 
Method Purpose 

accept () Accepts a new connection and returns two values: a new socket 

object to be used to transfer data and the address of the socket 
that this object is talking to 
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Table4.30. socketo Methods 


Method 

Purpose 

bind() 

Binds the soeket to a port address 

close () 

Closes the socket 

connect () 

Connects to another soeket 

getpeername() 

Returns an IP address and the port to which the soeket is 
conneeted 

getsocketname() 

Returns an IP address and the port of its own soeket 

listen() 

Starts listening on a given port, waiting for other soekets to 
connect 

makefile() 

Creates a fde objeet that you can use read ( ) and write () on 

recvfrom() 

Returns the data string received firom the soeket and the IP 
address that has originated from the socket 

send() 

Sends the date string to the socket 

sendto() 

Sends the data string to the soeket hosted by hostame at the 
provided port 

setblockingflag(i 

• Blocks all read/write operations 

shutdown() 

Shuts down the elient soekets or the server soekets or both 


can be used to create both sides of a conneetion (which are usually referred to as the 
Client- side and server-side). The socket () module implements a number of functions, 
as listed in Table 4.29. 


Function 

Socket() 
gethostname() 
gethostbyname() 
gethostbyaddr() 

getprotobyname() 
getservbyname() 


Table 4.29. socketo Functions 
Purpose 

Creates and returns a new socket object 
Returns the hostname of the loeal maehine 
Converts hostname to an IP address 

Returns a tuple containing the hostname, hostname alias list, and 
hostname IP list 

Returns a constant value equivalent to the protocol name 
Returns the port number assoeiated to the Service and protoeol pair 


Once created, each socket object has access to a number of methods, as listed in Table 
4.30. 
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NOTE 


socket.ssio can be used to set up a secure SSL connection. The secure connection 
uses OpenSSL, which is also supported in the socket module. 

Let's get Python to create a network connection—in this case, a TCP connection (see the 
upcoming sidebar for more information on TCP and UDP). In order to set up the server 
side of the connection, Python needs to take the following steps: 

1. Create a socket. 

2. Bind the created socket to an available port. 

3. Start listening on that port. 

4. Check the port periodically for new connections coming in. 

5. When a connection comes in (firom the client side), the server processes the 
request and sends it back to the client. 

Taken one at a time, these steps are fairly straightforward to implement. To create a 
socket, you first import the socket module and then create an instance of a socket; this 
requires a call to the socket constructor. The code looks like this: 

# Import the socket() module 
import Socket 

# Call the Socket constructor 
created_socket=socket.socket(family, type) 


Typically, the family designated in the socket constructor is set as af_inet, which is an 
Internet-type socket, or a socket that communicates between different machines. You 
may also run into the af_unix family, which is used for a UNIX-type socket and is 
normally used when sockets communicate with each other on the same machine. 

For a type designation you would see sock_stream for a stream or TCP connection or 
S 0 CK_DGRAM for a datagram or UDP connection. If you wanted an Internet TCP 
connection, the socket constructor would look like this: 

server socket = socket.socket(socket.AF INET, socket.SOCK STREAM) 


After creating a socket, you need to bind the socket to a port. To do so, you use the 
bindo method: 

Socket.bind(address) 


The socket is of course replaced with your socket instance, and the address is a two- 
part tuple in the form of (host, port). If you wanted to bind server_socket to host 
lO.100.100.201 and port 9000, do this: 
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server socket.bind("10.100.100.201", 9000) 


Step 3 is to teli the server to start listening on the port, waiting for any connections. For 
this step you use the listen () method, like so: 

Socket.listen(backlog) 


backlog lists the maximum number of elients that can request connections from the 
server. In this example, you will set server_socket with a maximum of 10 
connections: 

server socket.listen(10) 


Now you need to set up a loop that waits for the client to request a connection. The loop 
needs to run an accept method to receive the client requests: 

connection, address = socket.accept() 


Finally, you set up Communications for the server and client using the send () and 
recv () methods. AU of this inside of a while loop in Python looks like the following: 

while 1: 

data_sent = "data to send client" 

client_socket, client_address = server_socket.accept() 
print "Connection established with", client_address 
client_socket.send(data_sent) 

Client Socket.close() 


The data sent variable sets the data that will be sent to the client. Then the socket 
accept () method grabs the client address to print on the following line. The contents of 
data_sent are then sent to the client, and the connection is closed with the close () 
method. 

The connection on the client side is even easier to code. There are only three things that 
need to be done: 

NOTE 

TCP versus UDP 

TCP/IP is a connection-oriented form of networking. It was originally developed by the 
US Department of Defense as a form of communication with built-in redundancy. Layer 
3 of the OSI model (the Network Layer) is provided by the Internet Protocol (IP), which 
provides the basic mechanism for routing packets back and forth on the Internet. 


TCP is short for Transmission Control Protocol. It is the main form of communication 
over the Internet (working on OSTs Layer 4). IP needs TCP because on Level 3, IP 
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doesn't understand the relationships between the packets it sends, and it doesn't perform 
any re-transmission. TCP handles the reliability by double-checking the paekets' arrival 
and eontroling sequencing of packets by keeping track of when each one arrives. With 
TCP and IP, you can have two-way connections between machines over the physical 
OSI layers, and, thus, all the cable, wires, phone lines, satellites, and wireless stations 
that make up the Internet. 

UDP is a different form of protocol that provides transport on OSTs Level 4 instead of 
TCP. UDP is faster because it doesn't track packets sent and it doesn't bother 
acknowledging their arrival. This, of course, is also less reliable. TCP guarantees 
delivery and the order of delivery, but UDP doesn't guarantee either, and since it doesn't 
have to waste time to double check, it can send packets to a destination more quickly. 

1. First, create a socket. 

2. Open a connection to the server socket via the address (the address being the 
hosfs IP and the port number it is listening on). 

3. If any data comes through the connection, process it and close the connection. 
Step 1 looks fairly identical to the server-side steps: 

import Socket 

Client Socket = socket.socket(socket .AD INET, SOCK STREAM) 


After the socket is created, Step 2 involves connecting via the server address; this is 
accomplished through the connect () method; 

Client Socket.connect("server hostname", 9000) 


Finally, any data received is processed via the recv () method (capped at 512 bytes in 
this example), printed, and then the client connection is closed via the close () method; 

data_received = client socket.recv(512) 

client_socket.close() 

print "Received from host", data 


Lef s try the sample again, only this time initiate a UDP connection instead of a TCP 
connection. With UDP, the server stili creates a socket and binds with the address and 
then begins listening. But at that point, the servefs obligations stop, and the rest is 
handled by the client. 

To start, when initializing the socket you must specify sock_dgram instead of 

sock_stream: 

server socket = socket.socket(socket.AF INET, socket.SOCK DGRAM) 
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And, in this case, the while loop action is shortened up to only receive the information 
from the elient (with a maximum number of bytes again) and display it: 


while 1: 

data sent, address = server socket.recvfrom(512) 
print address[0], "server sent: ", data_sent 


It is the elient, in this example, that does the rest of the work, Again, you need to 
speeify that the soeket is a UDP-type soeket: 

Client Socket = socket.socket(socket .AD INET, SOCK DGRAM) 


Then you speeify the data to send, make the eonneetion, send the data, and elose the 
eonneetion: 

data_sent = my_input("Data to send") 

client_socket.sendto(data_sent, ("server_hostname", 9000)) 

Client Socket.elose () 


How about an aetual example? How about setting up a soeket elient and a soeket server 
and send text data between them? (This eode ean be found in the Chapter 4 souree files, 
labeled UDP_Server .py and UDP_ciient .py, on the CD.) For the server, start by 
importing socket and then designate a host and a port as variables: 

# UDP_Server. py 
import Socket 

My Host = "127.0.0.1" 

My Port = 5555 


You are using the Standard loealhost address 127.0.0.1 beeause, by doing so, you ean 
then test the server and elient on the same maehine. Next, establish a UDP soeket 
instanee as before, and bind the soeket to My_Host and My_Port: 

# Create the socket instanee 

My Socket = socket.socket( socket.AF_INET, socket.SOCK DCRAM ) 

# Bind the socket to host and port 

My Socket.bind( ( My Host, My_Port ) ) 


And finally, add a while loop that reeeives the paeket from the elient: 

while 1: 

Received Paeket, address = My Socket.recvfrom( 1024 ) 

print "Paeket received:" 

print "From host:", address[ 0 ] 

print "Host port:", address[ 1 ] 

print "Containing:" 
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print "\n" + Received Packet 
# Send data back to client 
print "\ndata to client...", 

My_Socket.sendto( Received_Packet, address ) 
print "Packet sent\n" 


This time, you take advantage of the information that comes through the connection, 
print the data, and then send data back to the client. Afterwards, you close the socket 
connection. 

Now for the client: Again you need to import the socket, set up the variables, and create 
an instance of the socket: 

# UDP_Client.py 

# Import Socket and set up variables 
import Socket 

My Host = "127.0.0.1" 

My Port = 5555 

# Create the socket instance 

My Socket = socket.socket( socket.AF INET, socket.SOCK DGRAM ) 


Now you handle the sending of the data back and forth in a while loop: 


# while loop that handles the sending of the packets 
while 1: 

# Send the data packet to the server 

My_Packet = raw input( "Send Data to Server:" ) 
print "\nSending packet containing:", My Packet 
My_Socket.sendto( My_Packet, ( My_Host, My_Port ) ) 

print "Packet sent\n" 

# Receive information back from the server 

My Packet, address = My Socket.recvfrom( 1024 ) 

print "Packet received:" 

print "From host:", address[ 0 ] 

print "Host port:", address[ 1 ] 

print "Containing:" 

print "\n" + My Packet + "\n" 


Data is received through Python's useful raw input and sent to the server socket. The 
while loop stays open to receive information that it is expecting from the server, and 
then prints out the information. When you run the client and server, you are able to send 
a custom message back and forth; it looks something like Figure 4.23. 

Figure 4.23. UDP client server connection using the socket o module 
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Putting It All Together 


In this section you'll take a bit from each previous part in the chapter to create a sample 
game. This sample is ealled Snowboardl.py and ean be found along with its data files in 
this ehapters seetion on the CD. 

Snowboard! has a strueture similar to the Monkey_Toss .py sample from earlier, and 
you'll follow the same general steps during ereation: 

1. Import the neeessary libraries. 

2. Define any neeessary funetions, the only one in this ease being a 
Display_Message funetion for displaying splash text on the sereen. 

3. Define any game objeet elasses, in this case simpieSprite, Piayer, obstacie, 
and FinishLine. 

4. Create a main () funetion and set up Pygame. 

5. Draw and update the neeessary graphies utilizing groups and sprites within a 
whileO loop. 

Are you ready? Then break! 

Import the Libraries 

And the libraries are; 

import os 
import sys 
import random 
import pygame 

from pygame.locals import * 


'Nuff said. 

Define the Funetions 

You want to set up a funetion that will display text in the game window. Lefs eall this 
funetion Display_Message, and use it to display a "You Win!" or a "Game Over!" 
message at the game's eonelusion. The funetion will take three parameters: the aetual 
message, the game sereen, and the game baekground. You'll use pygame. font. Font to 
define the type of font to use, font. render to render the message in white (RGB values 
1,1,1), and use get_rect () . cen terx and centery to ensure the text plaeement is in 
the eenter of the window. 

# Generic funetion to place a message on sereen 
def Display_Message( message, sereen, baekground ): 
font = pygame.font.Font( None, 48 ) 
text = font.render( message, 1, (1, 1, 1 ) ) 
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textPosition = text.get_rect() 

textPosition.centerx = background.get_rect().centerx 
textPosition.centery = background.get rect().centery 
return screen.blit( text, textPosition ) 


As you see, our Display_Message function looks remarkably similar to the 
f ont. render example earlier in the chapter. 

Define the Classes 

Snowboard! will have four classes: SimpleSprite, which will be a base class for all the 
other classes, and a Piayer, obstacie, and FinishLine class: 


class SimpleSprite: 
class Piayer( SimpleSprite ): 
class Obstacie( SimpleSprite ): 
class FinishLine( SimpleSprite ): 


The SimpleSprite Is thc basls for all the others, and defines base methods for placing 
the sprite on the screen using blit () and then covering the sprite with the background 
to make it disappear. The default _init_ method can take a loaded image and set itself 
up as a rect (): 

# Base sprite class for all moving pieces 
class SimpleSprite: 

def init ( self, image ): 

# Can load an image, sets up w-In a rect() 

self.image = image 

self.rectangle = image.get_rect() 

def place( self, screen ): 

#Places the sprite on the given screen 

return screen.blit ( self.image, self.rectangle ) 

def remove( self, screen, background ): 

#Place under background to remove 
return screen.blit( background, self.rectangle, 
self.rectangle ) 


The FinishLine is a sprite that represents a movable line on the game board. The 
snowboarder must travel a number of screen lengths before reaching the finish, dodging 
obstacles on his way. 

You only need an init_ method and a move method for FinishLine to initialize it and 
then move it where you have established the end game to be: 


# Finish line - movable for game difficulty 
class FinishLine( SimpleSprite ): 

# Initialize and center 

def init ( self, image, centerX = 0, centerY = 0 ): 
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SimpleSprite. init ( self, image ) 
self.rectangle.centerx = centerX 
self.rectangle.centery = centerY 

#Finish line can move up and down depending upon game difficulty 
def move( self, xincrement, yincrement ): 
self.rectangle.centerx -= xincrement 
self.rectangle.centery -= yincrement 


The Obstacle sprite will be used to load up tree images, which the snowboarder will 
have to avoid, to place on the screen. Notice how the move () method is used: 

# Class definition for the trees to avoid 
class Obstacle( SimpleSprite ): 

# Initiate an object of the class 

def init ( self, image, centerX = 0, centerY = 0 ) : 

# Initiate with a loaded image and set as a rectangle 
SimpleSprite. init ( self, image ) 

self.positiveRectangle = self.rectangle 

# move obstacle to a specified location 
self.positiveRectangle.centerx = centerX 
self.positiveRectangle.centery = centerY 

# display that the object has moved position 

self.rectangle = self.positiveRectangle.move( -60, -60 ) 


The movement of these sprites will be dependent upon the playefs actions, and will 
require a complicated move method: 


def move( self, xincrement, yincrement ): 

#Move trees up as the player moves down the slope 
self.positiveRectangle.centerx -= xincrement 
self.positiveRectangle.centery -= yincrement 

# Change position for the next sprite update 
if self.positiveRectangle.centery < 25: 

self.positiveRectangle[ 0 ] += \ 
random.randrange( -640, 640 ) 

# Keep the rectangle values from overflowing 
self.positiveRectangle[ 0 ] %= 760 

self.positiveRectangle[ 1 ] %= 600 

# Display that the object has moved In position 

self.rectangle = self.positiveRectangle.move( -60, -60 ) 


You will also need to check, using a Collision_Watch method, for sprite eollisions 
with the snowboarder. The reetangular box that you use to detect the eollisions is 
actually a bit smaller than the graphics: 

def Collision Watch ( self ) : 

#Make the collision box smaller than graphic 
return self.rectangle.inflate( -20, -20 ) 


Finally, you need to define the Player class, which is the class that will actually control 
the snowboarder. This class must be able to accomplish several things. First, the 
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snowboarder's four graphics—default, going left, going right, and crashed—all need 
methods, and a method must also exist to load each graphic when it is needed. 

The piayer class speed should be controllable, which means you need three methods— 
one to determine if the Player class is moving at all, one for speeding up, and one for 
slowing down. 

The Player class also needs to watch for collisions with obstacie classes, and 
remember how far it has traveled so it can know when it passes FinishLine. 
Altogether, this works out to some ten methods: 

class Player( SimpleSprite ): 

def init ( self, images, crashimage, centerX = 0, centerY = 0 ): 

def Load_Image( self ): 

def Move Left( self ): 

def Move Right( self ): 

def Decrease_Speed( self ): 

def Increase_Speed( self ): 

def Collision( self ): 

def Collision_Watch( self ): 

def Are We Moving( self ) : 

def Distance Moved( self ) : 


We start with the _init_ method that establishes the loading graphic and the initial 
state of the Player: 

def init ( self, images, crashimage, 
centerX = 0, centerY = 0 ): 

# Initial image and player state 
self.movingimages = images 

self.crashimage = crashimage 

# Initial Positioning - top and center 
self.centerX = centerX 

self.centerY = centerY 

# Starts with the Player graphic facing down 
self.playerPosition = 1 

# Start with 0 speed - not moving 
self.speed = 0 

self.Load_Image() 


You use yet another version of Load_image to pull each version of the snowboarder 
graphic when needed: 

# Load the correct image 
def Load_Image( self ): 

# If the player has crashed - special 
if self.playerPosition == -1: 

image = self.crashimage 
else: 

# All other cases the self.playerPosition determines which 
graphic to use 

image = self.movingimages[ self.playerPosition ] 

# Notice that the SimpleSprite Is re-Initialized 
SimpleSprite. init ( self, image ) 
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self.rectangle.centerx = self.centerX 
self.rectangle.centery = self.centerY 


Now tackle movement. The following simply double-check that Player class hasn't 
crashed into something, and then change the player's position; 

#Player Is Moving left 
def Move Left( self ) : 

# Check for crashing, If so drop speed 
if self.playerPosition == -1: 

self.speed = 1 

self.playerPosition = 0 

# Otherwise start moving left 
elif self.playerPosition > 0: 

self.playerPosition -= 1 
self.Load_Image() 

#Player Is Moving Right 
def Move_Right( self ) : 

ttCheck for crashing 
if self.playerPosition == -1: 
self.speed = 1 
self.playerPosition = 2 

# Otherwise start moving right 

elif self.playerPosition < ( len( self.movingimages ) - 1 ): 

self.playerPosition += 1 
self.Load_Image() 


When moving down the hili, the Player class will have variable speeds. First use the 
Are_We_Moving mcthod to dctcrmine if the Player class is moving at all; 

# Is Player moving or does speed = 0 
def Are We Moving( self ): 

if self.speed == 0: 

return 0 
else: 

return 1 


Then we deline, increase, and decrease speed, which basically alters from 1 to 10 
variables that the game code will use to increase or decrease the obstacie movement 
rates: 

# Subtract 1 from speed 
def Decrease_Speed( self ): 

if self.speed > 0: 
self.speed -= 1 

# Add 1 to speed up to 10, 

# Double check to see If we crash 

def Increase_Speed( self ): 
if self.speed < 10: 

self.speed += 1 
# player crashed 
if self.playerPosition == -1: 
self.playerPosition = 1 
self.Load_Image() 
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Next, you need to keep track of the distance the piayer class has moved. You do this 
with two variables, xincrement and yincrement. These start at 0 and then increase as 
the Piayer class moves down the virtual hili. Additionally, if Player is faeing straight 
down, she travels a little bit faster than when she is traversing the hili. The distanee is 
also modified by seif. speed: 

def Distance Moved( self ): 

xincrement, yincrement = 0, 0 
if self.isMoving(): 

# Are we faeing straight down, then faster 
if self.playerPosition == 1: 
xincrement = 0 
yincrement = 2 * self.speed 
else: 

xincrement = ( self.playerPosition - 1 ) * self.speed 

yincrement = self.speed 
return xincrement, yincrement 


Finally, set up collisions. This includes the same sort of Collision_Watch you saw 
earlier with obstacle, and also a Collsion method that can change the Playerelasses' 
graphio if necessary: 

def Collision Watch( self ): 

#Slightly smaller box 

return self.rectangle.inflate( -20, -20 ) 

# Change graphic If necessary 
def Collision( self ): 

#Change graphic to piayer crashed 

self.speed = 0 

self.playerPosition = -1 

self.Load_Image() 


Create main() and Set Up Pygame 

The main () function is where all of the fun happens. The game needs a number of 
variables defined, some of which ehange constantly and others that never change at all 
(called constants). The first trick is to get all of these straight. 


def main () : 

#First set Constants (all capitalized by convention) 

# Time to wait between frames 
WAIT_TIME =20 

# Set the course to be 25 screens long at 480 pixels per screen 
COURSE_DEPTH = 25 * 480 

# Seeds the number of trees on the screen 
NUMBER_TREES = 5 

# Secondly set Variables 

# vertical distance traveled 
distanceTraveled = 0 

# time to generate next frame 
nextTime = 0 
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# The course has not been completed 
courseOver = 0 

# Randomly generated obstacle sprites 

allTrees = [] 

# All screen position sprites that have changed and are now "dirty" 

dirtyRectangles = [] 

# current time clock 

timePack = None 

# Total time to finish course 

timeLeft = 60 


There are a number of images and sounds you will be using (loeated in the Data folder 
under Chapter 4's code listing on the CD), so we need to teli Python where they are 
exactly and what you will call them: 

# The paths to the sounds 

collisionFile = os.path.join( "data", "THUMP.wav" ) 
chimeFile = os.path.join( "data", "MMMMMl.wav" ) 
startFile = os.path.join( "data", "THX.wav" ) 
applauseFile = os.path.join( "data", "WOW2.wav" ) 
gameOverFile = os.path.join( "data", "BUZZER.wav" ) 

# The paths to the Images 

# Place all snowbaord files Into girlFiles 
girlFiles = [] 

girlFiles.append( os.path.join( "data", "surferLeft.gif" ) ) 

girlFiles.append( os.path.join( "data", "surfer.gif" ) ) 

girlFiles.append( os.path.join( "data", "surferRight.gif" ) ) 

girlCrashFile = os.path.join( "data", "surferCrashed.gif" ) 
treeFile = os.path.join( "data", "tree.gif" ) 
timePackFile = os.path.join( "data", "time.gif" ) 
game background = os.path.join("data", "background2.png") 


Now, to initialize Pygame, set the game surfaee to be 640x480 pixels, make the box 
caption "Snowboard!", and make the mouse invisible, as the game code doesn't use it: 

# initializing pygame 
pygame.init() 

screen = pygame.display.set_mode( ( 640, 480 ) ) 

pygame.display.set caption( "Snowboard!" ) 

# Make mouse.set_visable = false/0 
pygame.mouse.set_visible( 0 ) 


Now that Pygame has been initialized and you have a window to play in, set the 
background to the nice snowy-hill-looking background2.png image: 


# Grab and convert the background image 

background = pygame.image.load( game background ).convert() 

# blit the background onto screen and update the entire display 

screen.blit( background, ( 0, 0 ) ) 

pygame.display.update() 
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Now you need to use Pygame to load the sounds and images to which you have 
established the paths: 


# First load up the sounds using mixer 
collisionSound = pygame.mixer.Sound( collisionFile ) 
chimeSound = pygame.mixer.Sound( chimeFile ) 
startSound = pygame.mixer.Sound( startFile ) 
applauseSound = pygame.mixer.Sound( applauseFile ) 
gameOverSound = pygame.mixer.Sound( gameOverFile ) 

# Next we load the images, convert to pixel format 

# and use colorkey for transparency 
loadedimages = [] 

# Load all the snowboard files which are In girlFiles 

# Then append them Into Loadedimages[] 
for file in girlFiles: 

surface = pygame.image.load( file ).convert() 
surface.set_colorkey( surface.get_at( ( 0, 0 ) ) ) 

loadedimages.append( surface ) 

# load the crashed surfer image 

girlCrashlmage = pygame.image.load( girlCrashFile ).convert() 
girlCrashlmage.set colorkey( girlCrashlmage.get at( (0, 0 ) ) ) 

# load the tree image 

treelmage = pygame.image.load( treeFile ).convert() 
treelmage.set_colorkey( treelmage.get_at( ( 0, 0 ) ) ) 

# load the timePack image 

timePacklmage = pygame.image.load( timePackFile ).convert() 
timePacklmage.set_colorkey( surface.get_at( ( 0, 0 ) ) ) 


There are three last things you need to do before jumping into the while () game loop. 
The first is initialize the Player snowboarder. Seeondly, set up all the Obstacle trees 
on the course. Finally, play the start up THX sound, just for effect; 

# initialize the girl-snowboarder 
centerX = screen.get width() / 2 

# Create and Instance of Player called theGirl 

# Use the crashimage, center horizontally and 25 pixels from the 

top 

theGirl = Player( loadedimages, girlCrashlmage, centerX, 25 ) 

# place tree Objects in randomly generated spots 
for i in range( NUMBER_TREES ): 

allTrees.append( Obstacle( treelmage, 

random.randrange( 0, 760 ), random.randrange( 0, 600 ) ) ) 

# Play start - up sound for effect 
startSound.play() 

pygame.time.set timer( USEREVENT, 1000 ) 


Drawing and Updating within the while Loop 

Now you need to set up the while loop that updates all the sprites, keeps track of time, 
and renders everything. The while loop will be set to run until the eourse is over: 

while not courseOver: 
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Then there are a few things you need to do with timing to make sure the game flows 
smoothly: 


currentTime = pygame.time.get ticksO 
# Wait In case we are moving too fast 
if currentTime < nextTime: 

pygame.time.deiay( nextTime - currentTime ) 
# Update the time 

nextTime = currentTime + WAIT TIME 


Then eheek for sprites that are "dirty" (that have ehanged and need to be updated). We 
remove any sprites that need to be removed and eheek to see whether a timePack 
should to be drawn (a timePaek will inerease the time left before the loop is exited, 
giving the player more time to reaeh the finish line): 


# remove objects from screen that should be removed 
dirtyRectangles.append( theGirl.remove( screen, 

background ) ) 

# Check all the trees 
for tree in allTrees: 

dirtyRectangles.append( tree.remove( screen, 
background ) ) 

# Check timepack 
if timePack is not None: 

dirtyRectangles.append( timePack.remove( screen, 
background ) ) 


Now throw in the event code that listens for a player hitting the keyboard. Use Pygame's 
built in poli () method to fili the event queue. The playePs eommands direetly affeet 
the Player instanee (theGirl) by ealling the appropriate methods: 

# get next event from event queue using poll() method 
event = pygame.event.poli() 

# if player quits program or presses the escape key 
if event.type == QUIT or \ 

( event.type == KEYDOWN and event.key == K_ESCAPE ): 
sys.exit() 

# if the up arrow key was pressed, slow down! 
elif event.type == KEYDOWN and event.key == K UP: 

theGirl.Decrease_Speed() 

# if down arrow key was pressed, speed up! 

elif event.type == KEYDOWN and event.key == K DOWN: 
theGirl.Increase_Speed() 

# if right arrow key was pressed, move player right 
elif event.type == KEYDOWN and event.key == K RIGHT: 

theGirl.Move Right() 

# if left arrow key was pressed, move player left 
elif event.type == KEYDOWN and event.key == K LEFT: 

theGirl.Move Left() 

# Update the time that the player has left 
elif event.type == USEREVENT: 

timeLeft -= 1 
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Use random to randomly create timePacks on the screen as the player travels down the 
mountain: 


# 1 in 100 odds of creating new timePack 

if timePack is None and not random.randrange( 100 ): 
timePack = FinishLine ( timePacklmage, 
random.randrange( 0, 640 ), 480 ) 


Now, as the theGiri class instance moves down the mountain, you need to make sure 
the sprites that handle the trees and the timePack are updated and redrawn. This only 
happens if Are_We_Moving is true: 

# update obstacles and timePack positions if the player Is moving 
# First check Are We Moving 
if theGiri.Are We Moving(): 

# Check theGiri x and y Incremented distance 
xincrement, yincrement = theGiri.Distance Moved() 

# Move all the tree sprites accordingly 
for tree in allTrees: 

tree.move( xincrement, yincrement ) 

# If there Is a timePack move It as well 
if timePack is not None: 

timePack.move( xincrement, yincrement ) 
if timePack.rectangle.bottom < 0: 
timePack = None 

distanceTraveled += yincrement 


Next handle the meat of the collision detection. Check all grouped tree sprites in the 
timePack using the Collision Watch method; 

# check for collisions with the trees 
treeBoxes = [] 
for tree in allTrees: 

treeBoxes.append( tree.Collision Watch() ) 

# Retrieve a list of the obstacles colliding with the theGiri 
Collision = theGiri.Collision_Watch().collidelist( treeBoxes ) 

# When colliding play a sound and subtract from the time left 
if Collision != -1: 

collisionSound.play() 

allTrees[ Collision ].move( 0, -540 ) 
theGiri.Collision() 
timeLeft -= 5 

# Determine whether theGiri has collided with a timePack 

# A timePack must exist first 
if timePack is not None: 

if theGiri.Collision Watch().colliderect( timePack.rectangle 

) : 

# Play a sound and Increase the time left 
chimeSound.play() 
timePack = None 
timeLeft += 5 
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There are only a few things left to do before yoou can exit the while () loop. First you 
want to draw any dirty or changed objeets, mainly the trees and the timePacks. You 
also want to check to see if theGiri has reached the finish line, and, if so, exit the loop. 
Finally, you want to check the time; once timeLef t has reached 0 the game will also 
exit the loop: 

# place objeets on screen 

dirtyRectangles.append( theGiri.place( screen ) ) 

for tree in allTrees: 

dirtyRectangles.append( tree.place( screen ) ) 

if timePack is not None: 

dirtyRectangles.append( timePack.place( screen ) ) 

# update whatever has changed 

pygame.display.update( dirtyRectangles ) 
dirtyRectangles = [] 

# check to see If we have reached the end of the course 
if distanceTraveled > COURSE DEPTH: 

# Set a flag that says we have won! 
courseOver = 1 

# check to see If our time has run out 
elif timeLeft <= 0: 

break 


Whew! Now, just a bit of wrap-up code at the end of main () and after exiting the 
while () loop. If you havc exited the while loop and courseOver is set to 1, that means 
the player reached the end of the course and should get praise. Otherwise she lost. 

if courseOver: 

applauseSound.play() 
message = "You Win!" 
else: 

gameOverSound.play() 
message = "Game Over!" 


Of course, you use your handy-dandy Display_Message function to teli the player what 
happened: 

pygame.display.update( Display_Message ( message, screen, 
background ) ) 


Use the event queue to wait for the player to gracefully exit the program: 

# wait until player wants to close program 
while 1: 

event = pygame.event.poli() 

if event.type == QUIT or \ 

( event.type == KEYDOWN and event.key == K ESCAPE ): 
break 
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Finally, close off the main () function and make sure main is called with this typical end 
to the Python program: 

if name == " main 
main() 
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Summary 

Wow, youVe come a long way. Just a few short 80 pages or so ago you were a newbie 
Python programmer; now you ean surf with the best of them! You should feel 
eomfortable ereating a game loop, loading sounds and graphies, and doing basio 
networking with Python now. 

Important points from this ohapter: 

• The two keys to Pygame are the surf ace and the rect. 

• Really understanding blitting and sprites ean greatly inorease your game's 
performanoe. 

• There is a ton of librarios that exist for doing things in Python. 

• Tkinter has more methods and oonstruots than you ean throw a stiok at. 

• Tkintefs pack (), grid () , and place ( ) methods are the key to organizing the 
Tkinter GUI. 

• There are tried and tested librarios for dealing with oommon development needs 
like networking and sound, most of whioh are unoomplioated. 
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Questions and Answers 


1 : Q: Why didn't you cover [popular game programming library]? 

A: A: There is so mueh out in Python land that it wouid simply be impossible to 
include detailed references to everything that is out there. Not only is the 
amount of development work immense, it is constantly changing. 

2 : Q: Which graphics library is the best one to use for my first best-selling 
game? 

A: A: Each library seems to have its own strengths and weaknesses. However, 
this important decision should be based on your projecfs needs, not on the 
features of any particular library. With the rapid change in today's technical 
World, I wouid also check and make sure a library has had recent updates and 
a number of faithful, experienced users before launching a project with it. 
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Exercises 


1: Use Load image to create a simple slideshow that switches between images 
every few seconds or with a keyboard click. 

2: What are the steps taken to create a simple game engine with Pygame? 

3: Change the event code in Monkey_Toss .py or Snowboard! to take mouse 
input instead of keyboard input. 

4: List at least three of the OSI network layers. 

5: Alter Load_Sound. py so that it is capable of playing a MIDI, MP3, or any 
file besides a WAV. 
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Chapter 5. The Python Game Community 


Even snakes are afraid of snakes. 

-Steven Wright 

Python's game-development community is extremely active, and literally dozens of 
prebuilt game engines are available through the GNU open-source community license. 
There are also specific tools and libraries for utilizing and creating art and graphics, not 
to mention resources for networking and massive multiplayer gaming. It is not possible 
within the contines of this book to list all of the active projects and awesome tools 
available to the young Python programmer; you just have to dive in and start 
researching. This chapter starts the process with tools and resources that I have had 
some good experiences with; I think if 11 be a good place to start. 
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Engines 


An engine is simply a tool, and this chapter focuses on tools and engines available that 
help you program games. These tools are all Python-based and open-source, and, for the 
most part, are geared towards the beginning programmer and so have easy-to-use 
interfaces. 

The Cyclon Online Gaming Engine 

The Cyclon Online Gaming Engine (COG for short) is an open-source computer game- 
authoring system. The System comes with a development application to facilitate game 
creation, a "fill-in-the-bla nk s" GUI that brings up Windows in which you set up the 
game information, player information, rooms, directions, items, events, and even define 
action verbs that can be taken in by the text parser. The development application is 
shown in Figure 5.1. 

Figure 5.1. The COG development application 



COG currently supports a semi-Myst interface, with photo-realistic screens, text-based 
input, and mouse company-point movement. Games created with COG are meant to be 
run Online via HTTP or through a Web browser interface. The engine can be found on 
Sourceforge at http://cogengine.sourceforge.net/ . 

Python Adventure Writing System 

The Python Adventure Writing System (PAWS) is a text adventure system developed 
by Roger Plowman. As with many Python-based game tools, PAWS is aimed at the 
non-programmer and consists of a game engine, a world library, and a play module. 
PAWS is fairly well documented, and comes with a few sample games and two great 
explanatory texts, one aimed towards first-time game writers and another, aimed 
towards code-heads, that explains how the Python sources work. Even the source code 
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itself is well documented—especially the sample games, which read like tutorials 
themselves. You can find PAWS on the CD accompanying this book under the Python 
section (see Figure 5.2). 

Figure 5.2. The PA WS engine at work 
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PAWS ineludes a few fun trieks to keep its games lively. For instanee, it has a say () 
function that takes the plaee of print in Python; say () has the special ability to read 
eommands for paragraph breaks, boldface, tities, and eoior. These trieks are especially 
helpful when designing a text-based game. say () also has a parse alias, Object, which 
is called p in the code for short. PAWS also includes a number of fun and unique 
classes, set up in the core game and in the universe library, for creating game objects 
and doing lots of useful things. These classes and what they are used for are outlined in 
Table5.1. 


Table 5.1. PA WS Classes 
Class Summary 

ciassActivatableitem Crcatcs itcms a playcr can tum on and off 

ciassActor Creatcs people, animals, monsters, and other things players 

will be able to talk to or fight with. Based on 

ClassBasicThing. 


ClassBaseObj ect 
ClassBasicThing 

ClassContainer 
ClassDirection 
ClassDoor 


Base class for creating all "things" the player can internet with 

Delines basic physical laws. Base for specialized classes of 
"things" 

Creatcs containers that can hold things 
Used to create direction traveled by the player 
Creatcs one side of a door 
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Table 5.1. PA WS Classes 


Class 

Summary 

CiassFundamentai 

The base root class of all the other classes. AU other classes 
are based on this parent 

CiassGameObj ect 

Creates the game object 

CiassGiobai 

Creates a global object 

Ciassitem 

Creates an object that can be taken and carried by the player 

CiassLockabieDoor 

Creates a lockable door 

CiassMonster 

Delines anything with combat abilities. Based on 

CiassActor 

CiassOpenabieItem 

Delines items that can open or close 

CiassParserError 

Stores error messages 

CiassPiayer 

Detines the player character object 

CiassRoom 

Delines room 

CiassScenery 

Creates props and atmosphere 

CiassSheif 

Creates a lixed shelf that items can be placed on 

CiassUnderHider 

Creates an item that drops contents when taken 


PAWS makes it very easy to develop games quickly if you're accustomed to Python. 
For instance, the directions a player can traverse are set up through a Python dictionary. 
An example map might be something like the following: 


MyRoom l.Map = {North: " 

Northeast: 
East: 

Southeast: 
South: 
Southwest: 
West: 

Northwest: 
Up: 

Down: 


You can't go that way.", 
"You can't go that way. 
"You can't go that way. 
"You can't go that way. 
"You can't go that way. 
"You can't go that way. 
"You can't go that way. 
"You can't go that way. 
MyUpstairsRoom 1, 
MyDownstairsRoom 1,} 


PAWS knows its maps well enough to figure out how to link rooms together or print out 
a string if thafs what you want to have happen when a player travels in a certain 
direetion. Items and rooms in PAWS are defined by using the elass and then overriding 
the appropriate defaults methods, like so: 

Myitem 1 = Classitem("Mine") 

Myitem l.Bulk = 1 

Myitem 1.StartingLocation = MyUpstairsRoom i 
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In this example, I defined an item, Myitem. The argument given ("Mine") is the noun 
descriptor PAWS will use to reference the item. The Buik () and startingLocation () 
methods (inherited from ciassitem) set up where the item will originally be found, 
along with its weight/size in the player's inventory. 

Other fun PAWS features include a parser that can be extended so that a programmer 
can add new verbs and adverbs, game daemons that can be spawned to run functions at 
every player turn, and "fuses" that will run a function after a delay of so many turns. 
There is even a debug mode that allows you, for testing purposes, to trace commands 
and set variables while playing. 

To get the latest version of Paws, hit Roger's site, at 
http://members.nuvox.net/~zt.wolf/PAWS.shtml . 

PyPlace 

PyPlace, by Peter Goode (and based on work by Pete Shinners), is a tool for generating 
isometric maps—"Place" rendering in Python. 

The power behind PyPlace is a render.py module. This render model takes in a map 
object, which is basically a three-dimensional array, and uses the map to render an 
isometric view map with a number of square tiles (which are provided in a .png format). 

Unfortunately, the project has been in alpha for quite a while, and it appears as though 
development on the project has stopped. Stili, for the guru, this could be a good starting 
place for an isometric game engine. Find the project homepage at: 
http://www.mrexcessive.net/pvplace . 

And fmd it at Sourceforge project page at http://sourceforge.net/proiects/pvplace/ . 

Python Universe Builder 

The Python Universe Builder is a set of Python modules used to create text-based 
games or works of interactive fiction. PUB was originally built by Joe Strout and was 
subsequently revised by Terry Handcock for his AutoManga project. PUB is currently 
now under the wing of Joshua Macy, who has made efforts to update PUB for Python 
2.0 and document the project. The Sourceforge page can be found at http://pv- 
universe.sourceforge.net/index.html . 

NOTE 

The Basic Universe Simulator 

PUB's younger brother, the Basic Universe Simulator, is a set of Python code that 
demonstrates interactive fiction and Python. It is meant to be a short example of what 
Python is capable of, or a building block for a more complex game (the BUS is really 
just a few Scripts capable of parsing English sentence-like commands). BUS was also 
built by Joe Strout and can be found at his Website, http://www.strout.net/ . 
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PUB has a handful of modules for importing, as shown in Table 5.2. The modules are 
objeet-oriented, and have several big base classes grouped around objects that players 
interact with and verbs that the PUB uses to translate player commands. 


Table 5.2. PUB Modules 


Module 

Function 

demo 

Contains a simple demo game 

gadgets 

For building specific objects 

pub 

Contains globals 

pubobj s 

Contains Standard objects 

picklemod 

For saving (pickling) entire modules 

pubscore 

Contains datatypes, functions, and constants 

pubtcp 

Used for network support 

pubverbs 

Contains Standard verbs 

tcpdemo 

Used for MUD adaptation 


PUB also has classes for schedulers, commands, the parser itself, and events, which can 
be used to create everything used in the engine. 

After importing PUB, you can begin building MUD-like rooms and areas fairly quickly. 


# Create a room with module pubobjs and method Room 
MyPrisonRoom = pubobjs.Room("Dungeon Prison Cell") 

# Describe room with desc method 

room.desc = "You're in a small barred cell with walls of stone.X 
To the north is a rusty Iron-barred door. \ 

A small bowl filled with water lies In one corner of the room." 

# Establish north exit exits 

room n= Exit("north,n,out,bars,door") 

# Describe exit 

room_n.desc = "The door appears to be unlocked." 

# Add object Into the room 

water = pubobjs.Liquid("water,liquid") 

# Describe object 

water.desc = "It appears to be ordinary water, and fairly clean. 


This example first creates a sample room called MyPrisonRoom using pubob j s. Room, 
and then describes the room and establishes exits with the desc () and Exit () method 
calls. Then an object, in this case a Liquid () object, is created within the room and 
described in a similar way. Notice how creating an object in a room and creating the 
room itself are nearly identical. 

PUB's biggest strength is likely its sentence parser, which allows fairly complex input 
from players ("Get the dragon and put it in the shoe..."). 
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The Sourceforge page provides a few sample games (including a sample game that has 
been turned into a MUD version) and a template seript that handily shows, via 
comments, where objects must reside. The source eode itself is also available and fairly 
well commented. 

The Pyzzle Game Engine 

Pyzzle is a free (under the GNU publie license), pre-built game user-interface in the 
spirit of the Myst and Riven (it is included in this book's CD under the section on 
Python). Authored by Andrew Jones and written in Python and Pygame, the engine 
ineludes the following features: 

• A modular rendering interface capable of using OpenGL, SDL, or DireetSD. 

• Runs on several platforms (Windows, NT4, OSX, BeOS, FreeBSD, IRIX, and 
Linux). 

• Full API using Python scripting. 

• Support for different display sizes (640x480, 800x600, 1024x768, and so on). 

• Ambient sound, musie, and sound effeets (using WAV fdes). 

• Over-slide images (formats include BMP, GIF, PNG, JPG, PCX, and TGA), text 
using True Type fonts, and movie playback using MPEG fdes. 

• In-game objects that players can carry. 

• Zip navigation option. 

• Customizable color graphical cursors. 

• Slide-like Riven-style area transitions. 

• Basic menus. 

See Figure 5.3 for a look at Pyzzle's packaged demo game in action. Pyzzle is composed 
of the handful of modules listed in Table 5.3. 


Figure 5.3. The Pyzzle demo game showing the engine at work 




Table 5.3. Pyzzie Modules 


Module 

Use 

AmbientSound 

Defining ambient sounds and musio 

Image 

Defining over-slide images 

Movie 

Defining movies 

Obj ect 

Defining objeots 

parameters 

Controlling the global game parameters 

paths 

Defining the default paths 

Pyzzie 

The base engine 

Slide 

Defining slides. The basio graphios unit 

Sound 

Defining sound effeots 

Text 

Defining over-slide text 


The API isn't quite fmished as far as doeumenting goes, but just opening up the demo 
game fdes (eheek demogame.py) and perusing them ean be quite revealing (and, of 
eourse, the souree eode is freely available). 

Onee Pyzzie has been imported, you use parameter methods to set the game 
parameters like sereen size and background eoior: 


#import Pyzzie 

import pyzzie 

from pyzzie import * 

# Set a few game parameters 

parameters.setScreenSize((800,600)) # window size in game 
parameters.setBackgroundColor((0,0,0)) # set background to black 


Then you use the paths module to set the paths to the WAV, MPEG, sereen, and other 
files: 


#Tell Pyzzie about a few paths to use. 
paths.setSlidePath(os.path.j oin('data', 'slides')) 

paths.setSoundPath(os.path.j oin('data', 'sounds')) 

paths.setImagePath(os.path.j oin('data', 'images')) 

paths.setMoviePath(os.path.j oin('data', 'movies')) 


You will need at least one slide, whieh is basieally a game sereen. It ean be easier to 
start off giving each slide a label: 


#define Slide containers 
MyStartingSlide = Slide() 
MySecondSlide = Slide() 
MyThirdSlide = Slide() 
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And then defining each slide; 


# Define slides 

MyStartingSlide.setNavType(Standard) 

MyStartingSlide.setSlideFile('MylmageFile.jpg') 
MyStartingSlide.setNavigation([MySecondSlide, MyThirdSlide,]) 
MySecondSlide.setNavType(Standard) 

MySecondSlide.setSlideFile('MyImageFile2.jpg') 

MySecondSlide.setNavigation([MyStartingSlide]) 


This would set and connect two different images as slides that could navigate to each 
other. Starting the game up requires two lines; 


# Set the starting slide 
pyzzle.setFirstSlide(MyStartingSlide) 
#start the game 
pyzzle.start () 


There is a lot more that Pyzzle can do. Each slide can include music, items, special 
effects, and special behavior defined for clicking and navigating. Text, objects, ambient 
sound, containers, and puzzle control logic can all be defined and used to make a great 
game. For the latest version of Pyzzle, check out its homepage on Sourceforge, at 
http://pvzzle.sourceforge.net/ . 
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Graphics 


What do 3DS Max, Lscript, Lightwave, Alice, Maya, Blender, Animation Master, 
TrueSpace, RenderMan, and Poser all have in common? Well, besides being graphic 
programs and 3D applications, they are all Python scripting interfaces. Python is ideal 
for the struggling artist; it's able to link up to industry gear and is perfect for creating 
quick custom tools or automating repetitive tasks. 

Alice 

Alice is a tool for developing three-dimensional graphics, built around the concept of 
"3D for everyone." Most 3D engines require the programmer to know extensive 
trigonometry, vector algebra, and other painful math. Alice is designed to provide non- 
programmers with access to 3D programming and interactive worlds. One of the things 
that makes Alice powerful is that it has a very straightforward, easy-to-learn GUI 
(shown in Figure 5.4) for placing, sizing, tweaking, and animating three-dimensional 
objects and spaces. 


Figure 5.4. The Alice GUI 



Alice is open source and made available by its current developers and Copyright holders, 
the Stage Three Research Group at Carnegie Mellon University, and can be found 
Online at http://www.alice.org . 

The worlds and content created with Alice are freely distributable, as long as the 
stipulations in the license are followed. The Alice project initially began at the 
University of Virginia, and over the years has received support in the form of grants 
from DARPA, Intel, Microsoft, NSF, Pixar, Chevron, NASA, the Office of Naval 
Research, Advanced Network and Service Inc., ONR, and the Python community itself. 
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Currently Alice supports two-dimensional graphic imports (via drag and drop or 
through its built-in billboard) and .ase files, which are ASCII Seene Export files used 
for exporting 3D wire-frames on several 3D modelers (ineluding 3D Studio Max). Aliee 
is also eapable of importing musio and sounds by using MP3 files. The engine oomes 
equipped with hundreds of models and sounds pre-built and paokaged for the newbie. 

Aliee actually has draggable programming oonstructs (for example, if/else statements 
and loops) that can be used to set the behavior of the models. Underneath the GUI is a 
oomplete language that supports methods, arrays, lists, funotions, reoursion, and so on. 

Aliee has reoently gone through a oomplete re-development, and work is ongoing to 
allow Aliee to export and import more formats and run on more platforms. Originally, 
Alice was completely Python—the core, the code, the whole enchilada. With the recent 
major rewrite (which has been ongoing since 1999), much of the Software has been 
rewritten in Java. However, the engine is stili scriptable via Jython. 

Jython is an implementation of Python. However, Jython is written completely in Java, 
and is integrated into Sun Microsoft's Java 2 J2EE platform. This means Jython has all 
the dynamic object-oriented features of the Python language, and also runs on any Java 
platform. 

In order to implement Python/Jython scripting in Alice, you need to first enable it. You 
can turn on Jython scripting under the Preferences menu. Select Edit, Preferences, 
Enable Jython Scripting, as shown in Eigure 5.5. 

Figure 5.5. Enabling Jython scripting in Aiice 's GUI 



Once scripting is enabled, every object within the Object Tree (the top left-hand 
window, which includes any instance of three-dimensional objects, ineluding the world 
itself) is script editable with a right-click of the mouse, or through one-line Scripts via a 
"go" executable line (see Eigure 5.6). You can also access Scripts when editing methods 
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(Alice has a built-in method editor) with two draggable tiles called Script and Script- 
Defined Response. 

Figure 5.6. Editing a penguin object script from the object tree 



The Script tile allows you to type in code that will be run when that script method is run 
in the Alice engine. The Script-Defined Response is used to fire pre-composed Alice 
animations. 

Objects in Alice can be called, using their names, through Scripts, and their properties 
and variables are accessed just like member variables: 


Penguin.isShowing = false 


AU of this is pretty powerful—not only can you script objects via Python/Jython, but 
with Jython you also have access to the entire Java API. The Scripts can also call built- 
in Alice animations and Alice's "RightNow" methods, like those outlined in Table 5.4. 


Method 

DoInOrder() 
IfElseInOrder() 

isShowing() 
ForEachInOrder() 
MoveAnimation() 


Table 5.4. Alice 's RightNow Methods 
What it does 

Runs a series of animations 

Runs animation list if the condition is met for if/else 
statements 

Sets subject to be visible or not visible 
Iterates through a list 
Moves subject 
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Table 5.4. Alice 's RightNowMethods 


Method 

moveRightNow() 
PositionAnimation() 
ResizeAnimation() 
resizeRightNow() 
rotateRightNow 
setOrientationRightNow 
SoundAction() 
TurnAnimation() 
turnRightNow() 
WaitAction() 
WhileLoopInOrder() 


What it does 

Moves subject immediately if given direction and amount 

Sets subject position in world 

Resizes subject 

Resizes subject immediately 

Rotates on given axis immediately 

Sets subjecfs orientation via 3D matrix immediately 

Plays given sound at specified volume 

Rotates subject 

Rotates subject immediately given amount 
Waits for given duration 

Runs through animation list while condition is true 


These methods (and many others—check out the Alice2 documentation) can be called 
on models within Alice, but also on Alice's camera (the "watcher" point of view) and 
other objects like lights. 

Let's say you wanted to define an animation function in Jython. You can de fine the 
animation just like you define any other function: 

def MyAnimation(MyObject): 

return MyAnimation 


In this case, the function MyAnimation will take in MyObj ect as an argument and send 
back MyAnimation as thc animation series you want the model to execute (assuming 
that the object will be an Alice model). Now lef s set the animation to do something: 

def MyAnimation(MyObject): 

turn = TurnAnimation(MyObject, right, amount=1.0) 
movel = MoveAnimation(Forward, amount =1.0, duration =1.0) 
move2 = MoveAnimation (Backward, amount=1.0, duration=l.0) 

MyAnimation = DoInOrder( 

MyObject.IsShowing = true, 
movel, 
turn, 
move2, 

) 

return MyAnimation 


You define movel and move2 to move forward and backwards using Alice's 
MoveAnimation mcthod. Thcn you set turn to givc thc modcl a spin using 
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TurnAnimation. Finally, you make sure the object is visible with MyObjectIsShowing 
and run your series of animations. 

AutoManga 

Although now nearly defunet, AutoManga is a solution for digital cell animation. 
Japanese Manga-style animation is the idea behind AutoManga, and the engine is 
implemented with Python Scripts that call C/C++ extensions for SDL routines. The 
engine was developed by Terry Hancock, has had a number of other contributors over 
the years, and originally was to be connected to the Python Universe Builder to handle 
interactive fiction and use XML for sequencing resource files. 

Much of AutoManga was completed, including lighting effects and the ability to pull a 
few different formats for background images and animation cells, but the project 
unfortunately hasn't seen much action in the past year or two. Stili, it is a good starting 
point for firame and cell based Python animation; the developer notes and files are 
located on Sourceforge, at http://automanga.sourceforge.net/ . 

Blender 

Blender is a 3D graphics suite with a tumultuous history. Originally, Blender was a 
rewrite of the Netherlands animation house NeoGeo's 3D toolset. One of the co- 
founders ofNeoGeo, Ton Roosendaal, also founded a spin-off company calledNot 
another Number (NaN). This company's model was to further develop and market 
Blender technology. Initially this company faired very well, raising millions of dollars 
and gaining thousands of customers, but it was hit with hard economic times. In 2001, 
the company announced bankruptcy and the investors closed down NaN. 

Blender, however, proved to have a strong will to live. Roosendaal started a non-profit 
foundation and began the "Free Blender" campaign with the idea of opening up Blender 
to the community as an open-source project. He worked with NaN's investors to agree 
to a plan wherein the Blender Foundation would be able to purchase the intellectual 
rights and source code of the Blender engine. Then, to the surprise of everyone, 
Roosendaal and several ex- NaN employees, with the help and support of Blender's 
loyal users, managed to raise 100,000 EUR in seven weeks to make the purchase. 
Blender was free, and continues to be free to this day, supported by developers and used 
by artists around the world, under the GNU GPL License. 

Blender can be used for 3D modeling, animation, game-engine scripting (in some 
versions), and rendering. Most useful is Blender's built-in text editor (see Figure 5.7) for 
Python Scripts, which can be used to customize tools, set up animations and effects, and 
even build sophisticated AI control over lighting and game objects. 

Figure 5.7. BlendeFs text editor readiiy opens a Biender Python script 
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Blender offers a number of Python modules (shown in Table 5.5) to use in seripting. 
Some of them are stili being ported into the newest version of Blender as of this writing. 


Table 5.5. Blender Python Modules 


Module 

Description 

Porting Complete 

Blender 

The main Blender module 

yes 

BGL 

The Blender OpenGL module 

yes 

Camera 

The Camera module 

yes 

Draw 

Display module 

yes 

Image 

The Image module 

yes 

IPO 

The IPO animation key module 

no 

Lamp 

The Lamp module 

yes 

Material 

The Material module 

no 

Mesh 

The Mesh module 

no 

Nmesh 

Low level mesh access 

no 

Obj ect 

The Object module 

no 

Scene 

The Scene module 

no 

Text 

The Text module 

yes 

Window 

The Window module 

yes 


To switeh to the seripting mode in Blender, press the Shift and FI 1 keys simultaneously 
or go to the current Window Type button and choose Text Editor. Click the Browse 


221 















Datablock button and choose Add New Blender to open a blank .py file. Blender will 
automatieally name the file TX:text; you ean change the name by elieking on it and 
typing in the new name (see Figure 5.8). 


Figure 5.8. Highlighted text Controls in Blender 
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To test out Blender, start by renaming a text file to MyFile.py, and then import the main 
Blender module. From that point on you have access to the Blender methods sueh as 

Obj ect: 


import Blender 

MyObj ect=Blender.Obj ect.Get("Some_Obj ect") 


When running Scripts on objects in Blender, you would normally have two Windows 
open. One would be a workspace with the object within, and the second would contain 
the Python script that you would run on the object. 

Let's say you needed to run some complex math on a Mesh or Nmesh in Blender. First 
you import Mesh or Nmesh: 

import Blender 

from Blender Import Nmesh 


Then grab the mesh object, its name, and its raw data using object and Nmesh methods: 

MyObj ect=Blender.Obj ect.Get("Some_Mesh_Obj ect") 

MyMeshName=MyObj ect[0] .data.name 
MyMesh=Nmesh.GetRaw(MyMeshName) 
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Finally, run your complex math on each vertex, replace the values in your objects, and 
have Blender redraw the object; 


for each vertex In MyMesh.verts: 

# complex math here 

# complex math here 

# complex math here 
Nmesh.PutRaw(MyMesh, MyMeshName) 
Blender.Redraw 


Blender a is an excellent demonstration of the power of open source and open 
community development. Blender's user base is extremely supportive and Creative, and 
is busily at work at making Blender the best appliance since toasters. You'll find 
Information on Blender at 

• The Blender community site, http://www.blender.or.g 

• The Blender foundation site, http://www.blender.org/bf . 

• The Blender release page, http://www.blender3d.org . 

Nebula 

Nebula is an open-source, 3D, real-time, multi-platform game engine that supports 
Direct X and OpenGL. The project is brought to us by the game studio Radon Labs, in 
Berlin. Nebula is actually implemented with C++, but what makes it super-fun is that it 
is also scriptable with Python, Lua, and Tcl/Tk. fll talk a bit more about Nebula later on 
in this book (specifically in the Lua sections). 

Panda3D 

Panda3D is a rendering engine for SGL. The core of the engine is in C++, but Panda3D 
also provides a Python scripting interface and utility code. fll talk a bit more about 
Panda3D in the section on commercial games later in this chapter. 

Poser 

The Poser Pro Pack and Poser 5 come equipped with Python scripting as an available 
resource for artists; this is mainly used to automate advanced functions in the interface. 
Python Scripts can be accessed from Poser's Window menu, which opens up a Python 
Scripts dialog box, as shown in Figure 5.9. 

Figure 5.9. Accessing Poser's Python Scripts dialog box 
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The dialog box can be used as a placeholder for commonly used Scripts. Clicking on a 
script with the Alt key on a PC or the Control key on a Mac will bring up a text version 
of the script that you can edit. 

When creating custom Scripts, much of the work on Poser is done through the Scene, 
which is part of the Poser import module; 


# First Import Poser module 
import poser 

# Create a scene 
MyScene = poser.Scene () 

# Then you would do things to the poser scene 

# And at the end re-draw the scene 
Myscene.DrawAll() 


Pretty nifty, huh? Poser actually has a very deep API for interacting with Python; it goes 
way beyond scenes and comes equipped with pre-defmed Scripts for you to use. There is 
also a fairly large knowledge base and plenty of sample Scripts within the community. 

Information on Poser can be found at Curious Labs's site, at 
http://www.curiouslabs.eom/products/poser4#productinfo . 
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Commercial Games 


Game engines and graphics are all well and good, but what about actual commercial 
games, you ask? You're in luck, for Python has slithered its way into many a shop. The 
language has been used as the primary scripting tongue for quite a few major games, 
and there are also a handful of game development tools, scriptable via Python, that have 
also been released. 

Eve Online 

Eve Online is a massive multiplayer online game that won the award for best online 
game in Game Revolution's The Best of E3 2002 Online Awards, and was also featured 
shortly after its release at 2003's E3 conference. Created by Iceland's CCP Games and 
released in 2001, Eve's world is a massive RPG science-fiction environment featuring 
photo-realistic graphics and a real space-faring feel. 

What makes Eve special for us is that its game-logic is controlled by Stackless Python. 
CCP used Stackless on both the client and server side to firee its programmers from 
many of the mundane tasks of model behavior and instead focus on the Creative parts of 
AI. Stackless also allows CCG to easily make changes to the game and game behavior, 
even while the game is running, which is extremely important for its persistent online 
world model. 

Freedom Force 

Ereedom Porce, a popular super-hero multiplayer game from Irrational Games, was 
nominated for handfuls of PC Gamer's annual 2002 awards, and Irrational is currently 
working on an expansion of the game. Irrational used NDL's Netimmerse game engine 
and Freedom Force was co-published by Crave Entertainment and Electronic Arts. 

Many of the game's functions were exported to the Python side, so that Python could set 
and move objects and control camera movements. The single-player levels were 
scripted with Python as well, in order to control mission control and cut-scenes. 

Python was used with custom extensions provided by the Freedom Force engine, and 
the key to using these extensions is understanding the scripting guides, which you can 
download from Irrational games at 

http://www.irrationalgames.com/modforce/Editor/script.htm . 

Freedom Force launches two Python Scripts (located in its system folder): startup.py and 
init.py. Both of these files are used to set the data paths for the game; by adding to the 
default path, you can change which module f f (Freedom Force) loads up at the 
beginning: 

import ff 

ff.DefaultPath = "MyModule;data" 


Python Scripts control the flow of a module or adventure and can be used to script 
missions, create events that spawn new enemies, check for mission success and failure, 
trigger speech, and run cut-scenes. Each mission has a single script file (called mission. 
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py) with which it is associated and must be in the same folder as mission.dat (this file is 
commonly know as a mission script). 

There are also level offshoots, ealled briefings and intermissions, that are loaded in 
between missions. These are seripted in the same way as missions but use a base.py file 
and a base.dat file instead. 

The eustom extensions provided by the Freedom Foree engine are huge. Everything 
from AI to Object eontrol to missions to eamera movement is eompletely aeeessible via 
the Python seripting interface. Let's take a look at one example, a eut-scene snip from 
Freedom Foree. The Freedom Foree eamera has a number of methods for using eut- 
seenes, as illustrated in Table 5.6. 


Table 5.6. Freedom Foree Cut-Scene Methods 

Method Purpose 

piay () Plays a eut-seene 

isPlaying () Determines whether a eut-seene or seripted sequenee is 

eurrently playing 

startcs () Starts a eut-seene 

endcs () Ends a eut-seene 

endBriefingcs () Ends a briefing 

startcsNormaiScreen () starts a eut-seene but doesn't go into widesereen mode 
isCSPlaying () Retums true if a eut-seene is eurrently playing 

playTransition () Plays the logo transition 


Using these methods to start and stop a eut-seene would look like the following: 

# Define Cutscene 
MyCutscene = [ 

( 

# Start Cutscene 
"Startcs 0 ", 

) 

# End Cutscene 
"endCS()", 

) 


Those who have been paying attention will notiee that eut-seenes in Ereedom Eoree are 
Python lists; here is the same eode eondensed to one line for familiarity: 

MyCutscene=[(iteml,)(item2,)(etc)] 
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Later in the code you call the piay () function and viola! The MyCutscene cut-seene 
would run: 

play(MyCutscene) 


Of eourse, this eut-seene doesn't do mueh at all, but thafs where FF's eamera eontrols 
eome in. The eamera is enabled by a Camera_LookAt0bj ect () command and released 
baek to the player with the Camera_Release () eommand. Camera_LookAtOb j ect () 
ean be set with a number of eommands eommon to the FF eamera, as shown in Table 
5.7: 


Table 5.7. Freedom Force Camera Controls 


Command 

Description 

obj ectName 

The objeet to traek 

camDist 

The zoom distanee 

camPitchRot 

Angle of pitch around object right vector, in degrees 

camYawRot 

Angle of yaw around object up vector, in degrees 

camSpeed 

Time in seconds it will take to complete the move 

movePathMode 

Set camera snap (cpm snap, cpm scrollto, cpm homing, or 
CPM simplepath) 

camAction 

Set camera move (ca move) or tracking (ca track) 

callbackFunc 

Sets a Python script function to call when finished 

fUser 

User defmed data 


Given the eamera eontrols in Table 5.7, you ean move the eamera around the main 
player or protagonist: 

MyCutscene = [ 

( 

"startCS 0 ", 

"Camera LookAtObject('My Player',- 

195.30.384.3, CPM_SCROLLTO,CA_MOVE)", 

"Camera LookAtObject('My Player 

200.20.320.3, CPM_SCROLLTO,CA_MOVE)", 

) 

"endCS()", 

) 

] 


Table 5.7. Freedom Force Camera Controls 

Command Description 

ob j ectName object tO track 
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Command 

camDist 

camPitchRot 

camYawRot 

camSpeed 

movePathMode 

camAction 

callbackFunc 

fUser 


Table 5.7. Freedom Force Camera Controls 
Description 

The zoom distance 

Angle of pitch around object right vector, in degrees 

Angle of yaw around object up vector, in degrees 

Time in seconds it will take to complete the move 

Set camera snap (cpm_snap, cpm_scrollto, cpm_homing, or 
cpm_simplepath) 

Set camera move (ca_move) or tracking (ca_track) 

Sets a Python script function to call when finished 
User defmed data 


Not bad for a quick delve into the Freedom Force API—and weVe really just begun. 
There are actually a number of other camera commands to set wide-screen, introduce 
camera jitter, snap to objects or markers, fade in and out, and so on. Outside of the 
camera there are whole suites of functions and methods to set up narration, music, and 
sound effects, control NPCs and characters, set mission objectives and game flow, and 
so on and so on. 

Severance: Blade of Darkness 

Severance: Blade of Darkness is a fantasy combat game firom Codemasters / Rebel Act 
Studios (which is now defunct). It is a mature-audience game released in 2001 along 
with a level editor (called LED) and a set of tools (called RAS) for making levels and 
mods, which are, of course, based on Python and wholly scriptable. A Blade of 
Darkness level generally includes: 

• A .bw file which has the map architecture details, compiled firom the LED map 
editor (uncompiled maps are .mp files). 

• .mmp files, which are files with the textures used in and on the map. 

• One or more Blade of Darkness (BOD) files that de fine the objects and 
characters that inhabit the mod. 

• A number of Python Scripts that initialize and make objects and npcs and so on. 

• A level file (.Ivl) that loads things up to the game engine (the .mmp bitmaps and 
the .bw map file). 

The LED editor is shown in Ligure 5.10 (notice Python on the top toolbar). 

Figure 5.10. The LED editor with an open sample Ule 
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In the Python Scripts, you'll find that objects (weapons, torches, and so on) are usually 
defined with a objs.py fde, players with a pl.py fde, configurations with a cfg.py fde, 
the placement of the sun and its position with a sol.py file, and any water coordinates 
with a agua.py fde. 

Take a look at a sample agua.py file; 


import Bladex 

pooll=Bladex.CreateEntity("pooll", "Entity Water", 72000,39800, -2000) 

pooll.Reflection=0.9 

pooll.Color=90,20,20 

pool2=Bladex.CreateEntity("pool2","Entity Water",116000,39800,54000) 
pool2.Reflection=0.1 
pool2.Color=60,10,10 

pool3=Bladex.CreateEntity("pool3","Entity Water",116000,39700,46000) 
pool3.Reflection=-0.5 
pool3.Color=0,0,0 


First, the necessary Bladex libraries (which hold most of the neeessary eommands and 
functions) are imported. CreateEntity is then called on to create three separate pools 
of water at three separate locations. Once instantiated, each pool is then further defined 
with the Reflection and Color methods. 

NOTE 

A handful of developers from Rebel Act started their own company called Digital 
Legends Entertainment at http://www.digital-legends.net/ shortly after RAS closed its 
doors. They are eurrently foeused on produeing their first game, Nightfall Dragons at 
http://www.nightfalldragons.com . 
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ToonTown 


ToonTown, an online cartoon style mulit-player game, is the latest from the Walt 
Disney Imagineering studio. Players create their own cartoon avatars and explore a rich 
World where they can meet and internet with other "toons," earn jelly beans to put in the 
bank, and buy things (like a toon house or items for a toon house). There is even a bit of 
conflict thrown in, in the form of a "Cog Invasion" that is threatening the city. 

Disney's ToonTown uses Python in a direct and powerful way. The ToonTown 
executable actually calls Python on the client when the program is instantiated. Python 
was also used in development of the game, particularly in the PandaSD rendering 
engine. 

PandaSD is powered by Python, DirectX, and the Fmod music and sound effects 
System. After being used to create Disney's ToonTown it was released to the open 
source community and is currently under even more extensive development by both the 
VR Studio and the Entertainment Technology Center at Carnegie Mellon University. 
ETC is working on making a simple installer for PandaSD (the current installation is 
somewhat of a bear.. .ahem), creating solid documentation, adding to the basic model 
import functionality, and creating tools like level and script editors. 

Note that there are two versions of Panda. One is the original release to the community 
from Disney, located on Sourceforge and found there at 
http://sourceforge.net/proiects/panda3d/) . 

The second version is the release from Carnegie Mellon's ETC, and can be found online 
at http://www.etc.cmu.edu/proiects/panda3d/downloads . 

Panda is capable of importing Maya and 3D Studio Max models, as well as the Standard 
.gif, .tiff, and .jpeg image formats. It has a fairly extensive API that is stili undergoing 
documentation. It can also be extended with the SDK, and the engine itself is tweakable, 
as the code has been released to the community. 

The two most important lines in any Pythoned Panda script are 

from ShowBaseGlobal import * 


and 


run () 


The first line imports the necessary Panda files (which takes quite a bit of time) and the 
second line runs the environment. Running these two lines in a script after installing 
Panda will create a large, blank, gray window. These two lines are the minimum needed 
to create a Panda environment. 

Panda3D is built around the scene-graph, which is a tree-like object hierarchy structure. 
Individual objects, which are normally 3D models or GUI elements, are called 
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NodePath objects. NodePath objects inherit behavior from their parents, and there are a 
number of built-in, base, pre-defmed NodePath objects in Panda. 

PandaSD models are either .egg or .bam. EGG files are ASCII format (and therefore 
readable by humans), and .bam is their corresponding binary format (for faster load 
times). You load a 3D object in Panda using its global loader object, like so: 

MySDobject = loader.loadModel("3Dobject.egg") 


AU loaded objects in Panda are, by default, hidden from view. To change this, take the 
loaded object (which is now a NodeObject) and change its parent to render; doing so 
will make the object render onscreen: 

My3Dobj ect.reparentTo(render) 


Once the object is loaded, you can call upon all sorts of fun methods to manipulate it, 
from setting the x,y, and z coordinates with setx (), setY (), setz () or 
setPos(x,y,z): 

My3Dobject.setx(4) # Moves the object 4 "feet: on the X coordinate 


to changing the heading, pitch, and roll with setHPR (heading, pitch, roll): 

My3Dobject.setHPR(50, 30, 0) # Changes the model heading by 50 degrees 

and pitches the 

model upward 30 degrees 


to changing the object's scale with setScaleO: 

My3Dobject.setScale(10) # sets the scale uniformly xlO in each 
direction (x,y, and z) 


Panda is also capable of handling events (mouse clicks and key presses), has a GUI 
System for creating UI elements like buttons and dialog boxes (which can be bound to 
Python functions), and can incorporate sound effects and music. 
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Beyond Python 


So what else is there besides games and graphics? Well, a whole heckuva lot, actually. 
Being the adaptable language that it is, you'll find Python sunning on rocks and 
slithering in the grass just about everywhere on the planet. The projects in this seetion 
may particularly pique your interest. 

Beyond 

One problem with 3D tities is the massive amounts of knowledge and work required to 
design, maintain, and update them. Another is the eonstant re-engineering each 
independent gaming company must fund and support in order to ereate the latest and 
greatest. Beyond is a reusable object framework for game design that was created to 
address these problems. The idea behind the Beyond project was to identify which parts 
of the proeess are works that could be reusable, and then wrap them up as eomponents 
in order to ereate robust, easily modifiable 3D games. Python was chosen for this 
project because of its adaptability to multiple platforms, and its extensibility. 

The first version of Beyond, Beyond 1, was the development project and platform for 
U02, which was to be an imaginary-planet, massively multiplayer game released by 
Origin Systems. Based on the Ultima fiction originally created by Richard Garriott, 

U02 had player avatars with highly customizable identities capable of interacting with 
objects and other players in a massive world. Unfortunately, U02 was dropped and 
never actually saw the light of day, but this has been a minor setback for one of the 
principle developers, Jason Asbahr, who now leads an open-source, virtual-world, 

MMP Python framework, Beyond 2. 

Beyond 2 is stili very young, with only Version 0.0.1 released, but, of course, it is being 
built on the backs of several other highly successful platforms, including the Nebula 
Device by Radon Labs, Beyond 1, and Twisted Python. 

Technically, the original Beyond 1 project was based on many languages, but Python 
had a particularly interesting role. Client-server Information is encrypted and passed 
through constructs called SimObjects using remote method invocations in Python. 

The simobject was a root object, or superclass, for all other objects. SimObjects were 
organized in an object-oriented hierarchy, and could perform actions by executing 
methods on themselves or other SimObjects. 

Beyond 1 was also data-driven and had a master game database. World builders were 
able to alter and expand the world by adding behaviors, entities, and data into the 
database without changing the actual runtime code. Clients (players) would connect to 
local Python area servers which eventually connected to a main data base server and the 
main game database. 

Sound libraries, network Communications, and graphics were all wrapped into Python as 
extensions using SWIG (short for Simplified Wrapper and Interface Generator; more on 
SWIG in Chapter 12). Functions in C and C++ are exposed as Python function objects. 
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Progress on Beyond 2 and Jason Asbahds other projects can be found at his Website, at 
http://www.asbahr.com/index.html . 

The site includes several papers he has presented on Python and Python games. This set 
of papers also includes a port of Python onto the Playstation 2 and Nintendo platforms. 

Pippy 

Pippy is a port of the Python language to the PalmOS currently under development at 
Endeavors Technology. Although stili young, the latest version runs on Palm OS 3.5 or 
higher. A handful of the Standard Python modules have been removed to reduce the 
code footprint, though these removals are mostly code features (like dynamic linking 
libraries) that aren't necessary on a Palm platform. Pippy can be fireely distributed as 
long as the Copyright notice is included; the latest versions can be found on its 
Sourceforge page, at http://pippv.sourceforge.net . 

A handful of Python features have been removed for smooth running on the Palm, 
including the following: 

• Floating point numbers/objects. 

• Complex numbers/objects. 

• Python parser and compiler 

• Documentation strings 

• Dynamic linking 

• Signals 

• Path-related code 

• File I/O (stdio and stderr are simulated) 

• Most of the Python library modules 

• Most of the Python extension modules 

Pippy does include a version of the popular Python Interactive interface and a keyword 
popup menu interface with both a Keywords and Modules menu that contain built-in 
Python names, reserved keywords, and a listing of the built-in and extension modules. 

Development work may stili be needed on Pippy to reduce the code footprint, and 
currently Pippy works on a reduced version of Python 1.5.2. There are a few issues to 
work out with the Palm's stack (work is underway to bring Stackless Python to Pippy) 
and Palm's dynamic heap, but the early project results appear promising, the key being 
an active community willing to take the project to the next level. 

Stackless Python 

Stackless Python is a development effort led by Christian Tismer, and is a Python 
variant that doesn't use the C stack. The Python interpreter is written in C, so at some 
level every Python action is executed via C. Mostly this is good, but sometimes having 
multiple instances of Python C code running on the stack can cause problems, for 
example with recursion and with object references that build up on the stack. 

Stackless has received quite a bit of community support and has been highlighted at a 
number of Python conferences. Several companies, including Twin Sun, IronPort, and 
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CCP Games have used Stackless in development. Stackless is a super-tool for Python 
Work using co-routines or micro-threads; the popular MMOG Eve Online is a good 
example of Stackless use in this case. Stackless has gone through a few variations, and 
Tismer continues to maintain, update, and further improve the concept, tirelessly 
making Stackless faster, more portable, and efficient. 

You can find more information on Stackless at Christian TismePs Website, at 
http://www.tismer.com/ . 

Twisted 

Twisted began its existence as an open-source, massive, multi-player game called 
Twisted Reality. Since then Twisted has become a way to create network applications, 
from network transports and protocols to secure client servers. Twisted is no longer just 
a toy. It is a competitive production server system, designed with a small footprint to 
run on low-end hardware and stili be capable of handling thousands of users. 

Twisted supports the following: 

• Win32 events 

• GUI (GTK, Qt, wxPython, Tkinter, and so on) 

• TCP, SSL, UDP, Multicast, and UNIX sockets and subprocesses 

• Scheduling 

• Threading integration 

• RDBMS event loop integration 

Twisted also comes with prebuilt implementations, including: 

• A complete Web framework 

• Frameworks providing facilities on top of SSH, FTP, and HTTP 

• An NNTP server framework 

• A user authentication system 

• An instant messenger 

Twisted has been the basis for a handful of other open source projects, including 
CVSToys, Hep, Bannerfish, Beyond 2, and DocmaServer. The users of Twisted include 
a number of high-profile companies like Masters of Branding, NASA, and Mailman. 

Twisted programs usually use the twisted.internet.app.Application function. The 
applications created with this function are actually Python objects and can be used along 
with the variety of built-in tools to create and manipulative these applications Twisted 
comes with, just like any other Python object. The process for creating an application in 
Twisted normally involves creating an application object and then choosing a reactor 
(twisted. inter net. reactor), which is basically a toolkit for running Twisted on 
different platforms, for the application. 

Reactors are the core of the event loop in Twisted, and they provide a basic interface to 
a number of Services, including network Communications, threading, and event 
dispatching. A reactor implements a set of interfaces, usually dependent upon which 
platform Twisted is playing on. After setting up an application and a rector, you can 
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implement Twisted network protocol parsing and handing with 

twisted.internet.protocol.Protocol. 


Twisted also has Factory classes (twisted. internet .protocol. Factory) wherc 
persistent configuration is kept. The default factory classes can instantiate each 
protocol. 

Programming in Twisted looks remarkably like Python network programming 
(surprise!). First you must import the reactor and protocol; 

from twisted.internet import reactor, protocol 


Then lef s say you wanted the protocol to react to a connection: 

class MyTwistedClass(Protocol): 
def MyConnection (self): 

# do something 

self.transport.loseConnection() 


Now set up Twisted listening on port 5555; 


def main(): 

factory = protocol.ServerFactory() 
factory.protocol = Echo 
reactor.listenTCP(5555,factory) 
reactor.run() 
if name ==' main ': 
main() 


Twisted itself can be found on its Sourceforge page at 
http;//sourceforge.net/proiects/twisted . 

Twisted also has an active community of users and developers who can be found online 
at the Twisted Matrix, at http;//twistedmatrix.com . 
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Summary 

Many impressive projects have been listed and explored in this chapter. Don't be fooled, 
however. For each engine that I spent time researching, I had to leave out at least three 
others, and for every Python-based game that I played I had to miss at least two others. 
This is just an appetizer for whaf s out there waiting for the Python game developer. 

Important points from this chapter: 

• Python use is fairly widespread. 

• It is becoming more common for games to ship with their own internal level and 
script editors, and Python is one of the commonalities between these tools. 

• There are a number of development efforts using Python to bring the 
complicated task of game programming to the non-programmer. 

• Most professional graphics tools include some sort of scripting interface that is 
Python-able. 
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Question and Answer 


1 : Q: Why didn't you mention (insert product/tool/program/ here)? 

A: A: Python is so widespread and so rapidly developing that it would be 
impossible to list all of the games, engines, and tools that utilize it. 
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Exercises 


1 : List five industry tools that are scriptable with Python. 

2 : List a few of the most common uses of Python in commercial games. 

3: Choose one of the engines in Seetion 1 of this ehapter to write a two- or three 
sereen game interfaee. 
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Part THREE: Programming with Lua 


Programming with Lua and becoming comfortable with the Lua interpreter are the main 
focuses early on in this part of the book. Part Three also covers Lua's C API and 
speeific industry game examples. Also ineluded is a elose-up look at LuaSDL. 
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Chapter 6. Programming with Lua 

Language exerts hidden power, like a moon on the tides. 

-Rita Mae Brown 

This chapter will offer a brief introduction to the Lua language. This is a speedy 
OverView, but the chapter does include a few common and useful examples. 
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Lua Executables and Debuggers 

Lua can be executed in chunks written in a file or in a string by using the following 
function's API commands, but normally a host program executes Lua. In UNIX 
Systems, Lua Scripts can be made into executable programs by using chmod and placing 
the #! /usr. local/bin/lua (or whatever the Lua path is) line at the top of a Lua file. 
Lua fides can also be executed via the Windows command line the long way (c: \iua- 
5.0\bin\Lua. exe file torun. lua), but it won't run with a double mouse click until 
youVe set up a path or a usable development environment for Lua. For now we'll just be 
using Lua with the interpreter, so do not fret about it. 

Lua doesn't have any built-in debugging facilities. It does, however, offer an interface 
with special functions and hooks that allow a programmer to construet profilers and 
debugging tools. These hooks are called when the interpreter enters or leaves a function 
or changes code. Most of these functions are new as of Lua 5.0, which is good because 
the older call and hook functions had the a reputation of being slow and possibly 
volatile. Common debug functions are listed in Table 6.1. 


Table 6.1. Lua Debug Functions 
Function Purpose 


debug.gethook() 

Returns 

debug.getlnfo () 

Returns 

debug.getlocal () 

Returns 

debug.getupvalue () 

Returns 

debug.setlocal () 

Assigns 

sebug.setupvalue () 

Assigns 

debug.sethook () 

Sets the 

debug.traceback () 

Returns 


current hook settings 
a table with information about a function 
name and value of the local variable 
name and value of upvalue 
a given value to a variable 
a given value to an upvalue 
given function of a hook 
a string with a traceback of the call stack 


For more information on the built-in debugging facilties, check out the Lua user 
manual, which is available firom the lua.org documentation page at: 
http://www.lua.org/docs.html . 

One interesting development tool is the LualDE by Tristan Rybak, which is an 
integrated environment for developing Lua applications (see LualDE in action in Eigure 
6.1). The environment is currently in Beta testing but is available for free for 
commercial or non-commercial use. Despite being a prototype, EualDE supports output 
for building and debegging messages, step-into- and stop-over-type debugger 
commands, breakpoints, and a callstack trace window. You can find the latest version 
(including source code) at Tristan Rybak's Website, at 
http://www.gorlice.net.pl/~rvbak/luaide/ . 

Figure 6.1. The LualDE environment with a simpie Lua source sampie 
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Language Structure 

As I mentioned, executions of Lua are broken down into units called chunks. Chunks 
are simply sequenees of statements, and are basieally equivalent to program bloeks. Lua 
handles a ehunk just like any language handles a funetion, so ehunks ean hold loeal 
variables and return values. 

Chunks may be stored in a file or in a string inside the host program. When a ehunk is 
exeeuted, first it is preeompiled into byte-eode for the Lua virtual maehine, and then the 
eompiled eode is exeeuted by an interpreter for the virtual maehine. Lua has no 
deelarations, so a ehunk may be as simple and short as a single statement: 

ehunk ::={single statement} 


Or it ean be big and eomplex: 


Chunk 


} 


event buffer = nil, 
last_update_ticks = 0, 
begin_time = 0, 
elapsed_ticks = 0, 
frames = 0, 
update_period = 33 
active = 1, 
screen = nil, 
background = nil, 
new_actors = {}, 
actors = {}, 

add_actor = funetion(self, a) 

assert(a) 

tinsert(self.new_actors, a) 

end 


Punctuation 

Lua uses C- and Paseal-like punetuation. This takes a bit of getting used to, espeeially 
when you're just eoming from Python. While Python uses spaces and tabs to keep 
statements separated, Lua utilizes braekets, quotes, parentheses, squiggly lines, and 
other deliminators, and spaees and tabs are pretty mueh ignored, whieh ean be 
eonfusing at first. A good praetiee is to use the interpreter often; beeause the interpreter 
expects eode to be properly braeketed off, it 

NOTE 

I talked a bit about Paseal in earlier chapters when discussing the history of eomputer 
languages. As you may reeall, Paseal is a high-level struetured programming language, 
whieh forces design with a very regimented strueture. 
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will complain immediately if you retum a line of Lua thafs missing something. For 
example, see Figure 6.2, in which our friendly interpreter reminds me that I left off the 
seeond " in the string assignment. 

Figure 6.2. The Lua interpreter compiains thatFve ieft off something 

important 



Statements in C are normally ended in a semieolon. In Lua this is optional, but you will 
stili see it eommonly done: 

a=l 

b=2 

--equivalent to 

a=l; 

b=2; 

--equivalent to 
a=l;b=2; 

Language Types 

Lua is a dynamically typed language, so variables themselves do not have types; only 
the values of the variables have types. The basic types in Lua are shown in Table 6.2; 

Variables ereated in Lua are visible within the bloeks in whieh they are created and are 
considered global unless the area is specifieally defined as local using the local 
keyword. After a code block is executed, loeal variables are destroyed. 

Booieans 

In Lua, ali values different firom false or nll are eonsidered true. This means that 
only nll and Boolean false are eonsidered false for the purposes of statement 
exeeution; everything else is considered true. As of Version 5.0, Lua has a built-in 
Boolean recognition of true and false. 

Try running the following lines in the Lua interpreter: 
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Table 6.2. Built-in Data Types 


Name 

Data Held 

Boolean 

Either false or true 

funetion 

Funetion stored as a variable 

nil 

Value nil 

number 

Real numbers (double preeision floating point) 

string 

Charaeter string 

table 

Assoeiative array (i.e., dietionary / hash) 

thread 

Independent threads of exeeution 

userdata 

C pointers stored as variable 

X = true 
print (x) 



print (not x) 

You will see that the interpreter is smart enough to know that if something is not true, 
then it must be false. You ean use Lua to test Boolean validity by using two equal 
signs to represent "is equal to," like so: 

print (0==100) 
print (1 ==1) 


Note that in Lua, true and false are not numerical values (0 and 1) like in some 
languages. 

Functions 

A really wonderful feature of Lua is that you ean assign funetions to variables. In faet, 
when you define a funetion in Lua, you are basieally assigning the text body of the 
funetion to a given variable. Funetions are deelared by using the funetion keyword, 
with the general syntax being: 

funetion name(args) does something end 


where name is the name of the new funetion, args is any arguments the funetion takes, 
does_something represents what the funetion aetually does, and end telis Lua the 
funetion is over. 

For example, here is a quiek funetion that prints a statement to the sereen: 

funetion MyfunetionO print("What's your funetion?") end 
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After creating a function, you can call it at will; 

Myfunction() 


You can also print the value of the function's memory address using print: 


print (Myfunction) 


When you run this last line in the interpreter, you can see that Lua notices that it's 
dealing with a function as well as retuming its memory address. 

Funetions ean take arguments as well, like in this example that takes an argument and 
assigns it to x: 


function Myfunction(X) print(X) end 


When you eall this funetion with Myfunction ( l ), the interpreter prints out what is 
assigned to x— in this ease a 1. You eould also assign the function a string with 
Myfunction ("hello") . If no argument is passed to the funetion, Lua automatieally 
assigns nil to the argument, and in the ease of Myfunction (), the interpreter prints 

nil. 


Sinee funetions can be stored as variables in Lua, they can then be passed as arguments 
to other funetions or they ean be retumed. This makes them fairly powerful ereatures in 
Lua-land. 

Nil 

Nil values mean that a variable has no value. You ean set values to nil to delete them: 


X = nil 


and you ean test to see whether a variable exists by eheeking to see if its value is nil: 


print (x==nil) 


Nil is the equivalent of no value, so if a variable is assigned nil, it eeases to exist. 

Numbers 

Lua supports the Standard add (+), subtract (-), multiply (*), and divide (/) operators. 
These ean be fun to play with after firing up the lua.exe and using the print statement: 


print (1+1) 
print (5*5) 
print (10/9) 
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If you run these lines in the interpreter, you will notiee that Lua automatically brings in 
floating point numbers and gives you l.llllllll as an answer to the third ehunk. Lua 
doesn't bother with rounding off like many other languages do. AU numbers in Lua are 
"real" numbers stored in floating point format. 

You ean assign numbers to variables by using the = sign: 


X=100 
print (x) 


Lua also supports multiple assignments: 

X, y = 2, 4 
print (x,y) 

X, y = y, X 
print (x,y) 


NOTE 

The act of setting the value of a variable is called an assignment. 
Lua supports the Standard arithmetic relational operators, including 


/ 


< 

> 

<= 

>= 

These should be pretty familiar to you by now. Lua also understands logieal and, or, 
and not. Logieal not inverts a logieal expression: 

not true = false 
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while logical and and or can be used and combined to form the logical statements 
programmers often need: 

true or false 
X = true and y = true 


NOTE 

CAUTION 

Lua does exhibit some strange behavior when ordering precedence in an equation. This 
behavior shows up when running through equations from left to right and right to left. 
Normally, Lua figures out the left side of the equals sign first, but the order in which 
multiple assignments are performed is actually undefined. Lor instance, if the same 
values or tables occur twice within an assignment list, then Lua may perform the 
equation from right to left. The order preeedenee may also be ehanged in future versions 
of Lua. This can be a hassle, but it simply means that you should always use separate 
assignment statements when possible. 

An important topic for numbers and running equations is operator precedence, which is 
illustrated in Table 6.3. 


Precedence 

1 .(highest) 
2 . 

3. 

4. 

5. 

6. (lowest) 


Table 6.3. Lua Operator Precedence 

Operator 

^(exponentiation) 
not - (unary) 

+ - 

..(string concatenation) 

<><=>= ~= == 


Lua has an additional library that interfaces with the common C Math library functions. 
The library is available for access by Lua with a luaopen_math function and include a 
number of fun math tricks that should look familiar to C users and Math whizzes. The 
functions are listed in Table 6.4. 


Table 6.4. Additional Math Lua Library Functions 

Function Use 

math . abs AbsolutC valuc 
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Table 6.4. AdditionalMath Lua Library Functions 


Function 

Use 

math.acos 

Aro oosine 

math.asin 

Aro sine 

math.atan 

Aro tangent 

math.atan2 

As atan but usos signs of the arguments to oompute quadrant of the 
return value 

math.ceil 

Ceiling, returns smallest integer no less than given argument 

math.cos 

Cosine 

math.exp 

Exponent 

math.floor 

Returns largest integer no greater than given argument 

math.frexp 

Turns argument number into mantissa and exponent 

math.Idexp 

Returns X*(2^exp) 

math.log 

Logarithm 

math.loglO 

Base-10 logarithm 

math.mod 

Splits given into integer and fraotion parts 

math.pi 

Pi (3.14) 

math.pow 

Power, the base raised to exp power 

math.sin 

Sine 

math.sqrt 

Square root 

math.tan 

Tangent 

math.random 

Random number 


math. randomseed Seed number for random 

These functions all follow a similar pattern when used. Let's say I wanted the value of 
pi. rd do this: 

MyPy = (math.pi) 
print (MyPy) 

If I needed to find the tangent of a given number, fd do this: 

MyTan = (math.tan (10)) 
print (MyTan) 


Strings 
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Lua supports strings as text variable types. You can assign strings just like you would 
numbers, but you must be sure to include the quotes and parentheses, like so: 


myself = ("me") 
print (myself) 


You cannot use operators like + to concatenate strings, but Lua does allow you to 
concatenate strings using two periods, like in the following: 


myself = ("me") 

print ("Helio to "..myself) 


Besides double quotes, you can also set up strings using single quotes or double square 
brackets, as in the following; 


--this 

myself = ("me") 

--is equivalent to this 
myself = ('me') 

--is equivalent to this 
myself = ([[me]]) 


Lua supports these various methods so that you can place quotes within strings without 
using nasty escape sequences: 

Mystring = ([["quote"]]) 
print (Mystring) 


But Lua does support the Standard C-type escape sequences when using strings. These 
sequences are listed in Table 6.5. 


Sequence 

\a 

\b 

\f 

\n 

\r 

\t 

\v 

W 

\" 


Table 6.5. Lua Escape Sequences 
Translates to 

System beep 

Backspace, deletes the last character typed 

Form feed 

Newline 

Carriage return 

Horizontal tab 

Vertical tab 

Backslash 

Double quote 
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Table 6.5. Lua Escape Sequences 


Sequence Translates to 

\' Single quote 


It is important to note that when indexing a string in Lua, the first character is at 
position 1 (not at 0, as with C). 

Brackets have further uses when you're creating strings. For instance, they can be used 
to place strings on several lines of code, as shown in Figure 6.3. 

Figure 6.3. Using brackets to input a string over multiple lines 


‘*]C:\D(KiinMnU «nd $«tl1n^\Toni.fNOCH>0*tlctop\liMi-5.0\b1nM u«.«» 

Uun 5.0 Copyrlsht <C> 2883 Tec9r4ir« PUC Rio 

> function HyfunctionO 

>> print knous I'n biiildiny a fucntion'*> 

>> print <*‘si> it hasnt oxecuted ^t**> 

>> print <**lt i* waitinci for a ii^n fron 


Lua comes packaged with additional library string functions. These are not necessary to 
import Lua but are very helpful if you are working on an application with heavy string 
handling. These functions are listed in Table 6.6; the library is opened with the 

luaopen string function. 


Function 

string.byte () 
string.char () 
string.dump () 
string.find () 
string.len () 
string.lower () 
string.rep () 


Table 6.6. Lua 's String-HandlingLibrary 
Purpose 

Retums the internal numerical code of the character 
Retums a string of given length and internal numerical codes 
Retums binary representation for a given function 
Uses pattern matching to find the first match of a given string 
Retums a string's length 

Retums a copy of a given string in all lowercase letters 
Retums a string concatenated to specifications given 
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Function 

string.sub () 

string.upper () 

string.format 
0 

string.gfind () 
string.gsub () 


Table 6.6. Lua '§ String-Handling Library 
Purpose 

Retums a substring of the given string 

Retums a copy of a given string in all uppercase letters 

Retums a formatted version of a given string using C's printf style 
of arguments and mles 

Used to iterate over strings to mateh pattem 

Retums a eopy of a given string after mnning given arguments over 
the speeific string 


The string library also has built-in funetions for pattern matehing, allowing Lua to 
seareh through long strings or tables, mateh up pattems, and return them (ealled 
eapturing). These eontrols are normally preeeded by modulus; they are outlined in Table 

6.7. 


Table 6.7. Common Pattern-Matching Controls 


Symbol 

Pattern 

• 

All eharaeters 

%a 

All letters 

%c 

All eontrol eharaeters 

%d 

All digits 

%1 

All lowerease letters 

%p 

All punetuation eharaeters 

%s 

All space eharaeters 

%u 

All upperease letters 

%w 

All alphanumeric eharaeters 

%x 

All hexadeeimal digits 

%z 

Character with representation 0 


Using these funetions to find pattems and matehes is relatively straightforward using 
string. find. For instanee, here is a Lua ehunk that searehes for the letter "o" in the 
given string: 


MySearch = string.find('word', 'o') 

print (MySearch) 
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When this chunk is run in the Lua interpreter, you are given the loeation of o in the 
string, which is the second charaeter loeation, right after 'w' which is first. 

Let's say that you wanted to find four-letter words that begin with s in a given string. 
You can use period (.) as a wildeard: 


Mystring = 'Blah blah blah blah sand blah' 
Mystring2 = (string.find(Mystring, 's...')) 
print (Mystring2) 


This ehunk will find the word sand in the string at the 21 st character loeation after the 
first four Blahs. 

Tables 

Tables are the main data structure in Lua. Let me repeat that, because it's important: 
Tables are the main data structure in Lua. Instead of lists or tuples or dictionaries, Lua 
utilizes tables as its primary data holder. Tables are Lua's general-purpose data type and 
are capable of storing groups of objects, numbers, strings, or even other tables. Tables 
are created using curly brackets, like so: 

Mytable = {} 


If you were to print out Mytable (using print (MyTable) ), you would get a funny 
number, something like 0032bb99. This is the unique identifier and memory address 
that Lua has assigned to Mytable. 

Tables are used everywhere in Lua. They are the basic building block to creating all of 
the important programming constructs like queues, linked lists, and arrays. Tables can 
also function more like hashes and dictionaries than arrays and lists. You can add hash- 
like objects to a table by assigning a key/value pair, like so: 

Mytable = {Mynumber = 1, Myword = "Ikes!" } 


You can then refer to the table with the familiar 

print (Mytable.Mynumber) 
print (Mytable.Myword) 


Tables can also be used in an array/list-type way. You do this by creating a comma- 
separated bst of objects when creating the table. You can then access the table like an 
array, using brackets and numeric references, like so: 

Mytable = { 1,2,3,4,5, 6, 7, 8, 9,0 } 
print (Mytable [1]) 
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Notice, when you run this chunk in the interpreter, that the array/table starts at 1, not 0. 
The 0 value is aetually assigned nil, or no value. 


You can mix a dietionary-type table and array-type table together, making tables pretty 
versatile little buggers. Tables ean also eontain other tables: 

Mytable = { tablel= {a = 1, b = 2}, table2={c =3, d = 4}} 


Additional ways to manipulate tables are possible using the additional library functions 
listed in Table 6.8. 


Function 

table.concat () 
table.foreach () 
table.foreachi () 
table.getn () 
table.sort () 
table.insert () 
table.remove () 
table.setn () 


Table 6.8. Table Functions 
Purpose 

Retums eoneatenated tables 

Used to execute a given funetion over all elements of a table 
Executes given funetion over numerieal indiees (only) of table 
Retums the size of the table 
Sorts tables elements in a given order 

Inserts element at a given position, shifting all other elements 
Removes element from given position, shifting elements down 
Updates the size of a table 


These funetions all work in a similar way. For instanee, you ean use table. getn and 
table. insert to update a table entry, like so: 

Mytablelength = table.getn(Mytable) 

--Inserts 22 into the end of the table 
table.insert(Mytable, 22) 


You ean insert elements at a ehosen point in the list using table. insert: 
table.insert(Mytable, 10,100) 


You ean print out the eontents of the table using table. foreachi: 
table.foreachi(Mytable, print) 

Even though you ean treat a table as an array, keep in mind that it is stili table. You ean 
store whatever you want: 

Mytable[5] = "Hey, a string!" 
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So, if you were printing out a dictionary version of the table 

Mytable = {Mynumber = 1, Myword = "Ikes!" } 


you would use the f oreach funetion to print out eaeh key/value pair: 

table.foreach(Mytable, print) 


The next funetion ean also be used to iterate over a table. next takes a table and an 
index and gives baek the next key/value pair from the table; 

next(Mytable,"key") 


Tables are also objects in Lua in the sense that they have state, independent identity, a 
life eyele, and operations that ean be ealled upon them. The Lua programming model 
also has ways of implementing traditional OOP in the form of inheritanee, 
polymorphism, elasses, and late binding with tables. 

People eonsidered tables in Lua so impressive that in the latest version metatables were 
added as well. Every table and userdata objeet in Lua may now also have a metatable, 
whieh is an ordinary Lua table that further defines behavior. The eommands 
lua_getmetatable and lua_setmetatable allow you to manipulate the metatables of 
a given objeet. 

Weak tables were also added with Lua 5.0, whieh are tables whose elements are weak 
referenees. Unlike regular referenees weak referenees are ignored by Lua's garbage 
eolleetor.. Since weak tables do not prevent garbage eolleetion, they are useful for 
determining when other objects have been collected by the GC and for caching objects 
without impeding garbage eolleetion. 

Threads 

Threads allow programs to do multiple things at once. In a multi-threading model, eaeh 
task runs in a thread that is separate from other threads. There are many ways to 
implement multi-threading, and Lua's way is a bit unique. Lua uses a "cooperative 
multi-threading," using coroutines that aren't actually operating-system threads but are 
instead just blocks of code that ean be created and run in tandem. 

To create a coroutine, you first must have a funetion that the coroutine runs: 

funetion MyfunctionO 
print ("do something") 
coroutine.yield() 
end 
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You then create a eoroutine using coroutine. create: 
Mythread = coroutine.create(Myfucntion) 


Onee you have established a eoroutine, you ean eheek its status with 

coroutine.status: 

Mystatus = coroutine.status(Mythread) 
print(Mystatus) 


When run in the interpreter, this code will show that Mythread is suspended. To start or 
resume a eoroutine, use coroutine. resume. In this example, the interpreter will print 
do something, and then Mythread will exit by yielding. 

Yielding is key to coroutines. Coroutines must be able to yield System resources and 
pass eontrol to the next thread that needs it. The coroutine. yield is similar to the 
return funetion, and it exits the eurrent thread and frees up any resourees. 

If you run the Mystatus eode a seeond time: 


Mystatus = coroutine.status(Mythread) 
print(Mystatus) 


the status will show that the thread has already run by reporting dead. 

Userdata 

Userdata is used to represent C values in Lua. There are two types of userdata: full 
userdata and light userdata. Full userdata represents a block of memory and is 
eonsidered to be an objeet. A light userdata represents a pointer. 

Identifiers 

Identifiers in Lua ean be made up of letters, numbers, and underseores, but they eannot 
begin with a digit. Lua is ease-sensitive, so the strings hello and heiio are eonsidered 
different strings. There are a handful of reserved words that Lua keeps for itself and 
eannot be used as identifiers; these are as follows: 

and 

break 

do 

else 

elseif 
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end 


false 

for 

function 

if 

in 

local 

nil 

not 

or 

repeat 

return 

then 

true 

until 

while 

A Standard convention in Lua is that internal variables begin with an underscore and a 
capital letter, like Myvariable . 

Control Structures 

Control structures in Lua are similar to those in Lua's syntaetical parents C and Paseal. 
if, while, and repeat eommands are very common. The traditional if statement looks 
like the following in Lua: 

if true then block {elseif true then block} [else block] end 

An example of an if statement that prints whether x is less than 10 would be: 

X=1 

if x<10 then print ("x is less than 10")end 

You ean add a second else statement in ease x is greater than 10: 
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if x<10 then print ("x is less than 10")else print ("x is greater than 
10")end 


Loops 

One extremely common looping statement is the while loop, which looks syntactically 
like the following: 

while true do block end 


A second common looping construet is the repeat loop: 
repeat block until true 


Here is a sample Lua while loop that prints out a series of numbers: 

X = 1 

while x<10 do 
print (x) 
x=x+l 
end 


The sample is just as easy to implement using repeat: 

X=1 

repeat 
print (x) 
x=x+l 

until x==10 


The for loop, however, is what holds a special place in the programmer's heart. Lua has 
two versions of the for loop. The first one is used with numbers: 


for variable = var, var, var do block end 


Like in a typical for loop, all three expressions aren't necessary: 

for X=l, 10 do print(X) end 

This loop prints X as it iterates through the loop 10 times. 

The second version of for is used for traversing a table, and it is capable of iterating 
through each key/value pair of a given table: 

for variable {, var} in explist do block end 
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An example of this version of for iterating over a given table is as follows: 

Mytable = {1,2,3; word="hi, number=100000} 

for key,value in Mytable do print (key,value) end 


Included with this fun for is also a pairs () function for iterating key/value pairs: 

for key,value in pairs(Mytable) do print (key,value) end 


In this instanee, pairs () will iterate only over the array type table entries in the table; 

for index,value in ipairs(Mytable) do print (index,value) end 


Lua uses a return statement to return values from a function or a Lua chunk. There is 
also a break statement that can be used to terminate the execution of a loop and skip to 
the next statement that follows. Both return and break must be the last statements in a 
given block. 

Modules 

Modules, packages, namespaces: all are mechanisms used by languages to organize 
global names and space and avoid collisions. In Lua, modules are implemented with the 
all-important and versatile (you guessed it) table. Identifiers become keys within tables 
instead of global variables. A package may look like this: 

Mypackage = { 

functioni = function() dosomething{} end, 

function2 = function() dosomething!} end, 

function3 = function() dosomething!} end, 

functioni = function}) dosomething!} end, 

} 


Then the package can be called like this: 


call = Mypackage.functioni(arguments) 


Libraries 

Lua has a set of Standard libraries that provide useful and common routines. These are 
implemented directly through the Standard API but aren't necessary to the language, and 
so are provided as separate C libraries. There is a basic library, a library for string 
manipulation, one for mathematical functions, one for system facilities and I/O, one for 
debugging, and one for tables. The functions are declared in lualib. h and must be 
opened with a corresponding function, like in the following examples: 

luaopen_string 

luaopen_table 
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luaopen math 
luaopen_io 

A few of the libraries (math and string) were covered in the previous sections. The 
others will be covered here. 

The Basic Library 

The basic library provides much of Lua's base functionality. The commands involved 
are listed in Table 6.9. 

The coroutinefunctions are actually part of a sublibrary of the basic library. 

Input/Output Library 

Input and output are handled by two file handles. These handles are stored in two global 
variables: _input and _output, the former for reading and the latter for writing. 

_iNPUT and _0UTPUT are also equivalent to _stdin and _stdout. The common I/O 
functions are listed in Table 6.10. 


Tabie 6.10. Common Lua Input/Output Functions 


Function 

Purpose 

io.close 0 

Closes the given fde 

io.flush 0 

Flushes over the default output fde 

io.input 0 

Opens the named file in text mode and sets its handle to the default 
input file 

io.lines () 

Opens the given file name in read mode and returns an iterator function 
that returns a new line from the file each time it is called 

io.open () 

Opens a file in the mode specified and returns a new file handler 

io.output 

0 

Opens named file in text mode and sets its handle to the default output 
file 

io.tmpfile 

0 

Returns handle for a temporary file 

io.type 0 

Checks if object is a valid file handle 

file:close 

0 

Closes file 

file:flush 

0 

Saves any written data to file 

file:read 

0 

Reads the file according to given formats 

file:lines 

0 

Returns an integrator that returns a new line from the field each time it 
is called 

file:seek 

Sets and gets the file position 
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Table 6.10. Common Lua Input/Output Functions 

Function Purpose 

0 

file:write Writes the value of each of its arguments to the filehandle file 
0 


Function 

assert () 
collectgarbage () 

coroutine.create 
0 

coroutine.resume 
0 

coroutine.status 
0 


Table 6.9. Lua '§ Basic Function Library 
Purpose 

Issues an error when its argument is nil 

Forces a garbage collection eycle and returns the number of 
objeets eolleeted 

Creates a new eoroutine 

Starts or continues coroutine execution 

Returns status for a coroutine 


coroutine.wrap () 
coroutine.yield () 
dofile 0 

error () 

_G 

getfenv () 
getmetatable () 

gcinfo () 

ipairs () 
loadfile () 
loadlib 0 
loadstring () 
newtag () 
next () 
pairs 0 
pcall 0 


Creates a new wrapped coroutine 
Suspends coroutine execution 

Opens a given file and executes its contents as a Lua chunk or 
as precompiled chunks 

Calis the error handler and then terminates the last protected 
function called 

Holds the global environment 

Returns current environment in use by a given function 

Returns objeets'_ metatabie field value or else nii for no 

metatable 

Returns dynamic memory use and garbage collector threshold in 
kbytes 

Iterates over a table 
Loads a file as a Lua chunk 
Links a program to a C library 
Loads a string as a Lua chunk 

Returns a new tag - equivalent to the API function lua_newtag 
Allows a program to traverse all fields of a table 
Iterates over tables 

Calis a function in protected mode with given arguments 
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Table 6.9. Lua 's Basic Function Library 


Function 

Purpose 

print 0 

Reeeives arguments and prints their values using the strings 
returned by tostring 

rawequal () 

Cheeks to see if two values are equal 

rawget () 

Gets the real value of an index within a table 

rawset () 

Sets the real value of an index within a table 

require () 

Loads a given package 

setenv () 

Sets the environment to be used by a funetion 

setmetatable () 

Sets the metatable for a given table 

tonumber () 

Tries to eonvert an argument to a number 

tostring () 

Tries to eonvert an argument to a string 

type 0 

Returns the type of its only argument 

tinsert () 

Inserts an element at a given table position 

tremove () 

Removes an element firom a given table 

type 0 

Tests the type of a value 

unpack () 

Returns all elements firom a given list 

-VERSION 

Holds the current interpreter version (i.e. Lua 5.0) 

xpcall 0 

Calis a function in protected mode using err as the error 
handler 


System Facilities 

There are also a few System utility functions that can be included with Lua's built-in 
library. They are listed in Table 6.11. 


Function 

os.clock 0 
os.date () 
os.difftime () 
os.execute () 

os.exit 0 
os.getenv () 


Table 6.11. Lua System Facilities 
Purpose 

Returns an approximate CPU time, in seeonds, used by the program 

Returns the date and time aceording to given format 

Returns the seeonds between two given times 

Passes a command to be executed by the operating system. 
Equivalent to C's system 

Calis the C funetion exit to terminate a program 

Returns the value of a given environment variable 
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Table 6.11. Lua System Facilities 


Function 

Purpose 

os.remove () 

Deletes a given file 

os.rename () 

Renames a given file 

os.setlocale 

0 

Used as an interface to the ANSI C setlocale fiinction 

os.time () 

Returns current time 

os.tmpname () 

Returns a string with a filename that can be used for a temporary file 
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Memory, Performance, and Speed 


Like most high-level languages, Lua manages memory automatically, so that you don't 
have to worry about allocating memory for new objects and freeing it when the objects 
are no longer needed. Lua manages memory automatieally by running a garbage 
colleetor from time to time to eollect any objects that are no longer accessible to Lua. 
The garbage collector picks up all of Lua's objects, including threads, tables, and so on. 

Although this is not an issue when running the Lua interpreter, when calling Lua from a 
host, Lua's stack-in memory must be managed. Each function call in Lua needs one 
stack position for each argument, local variable, and temp variable, plus one position for 
bookkeeping. The stack should also have some 20 extra positions available. For small 
implementations of Lua (without, say, recursive functions), the Lua user manual 
suggests a stack size of 100. The default is 1,024. 

Figure 6.4. A Lua script interacts with the stack 



lua_Stat *lua_open (int stacksize) ; 


To release Lua, you close its state with the stack: 

void lua close (lua-Stat *L) ; 


This destroys all objects in a given Lua environment by calling the corresponding 
garbage-collection tag methods and firees all of the dynamic memory used by that state. 
You do not normally need to call this function because all resources are released when 
your program ends. However, long-running programs like Web servers or game-server 
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hosts may need to release States as soon as they are no longer needed so that the States 
don't grow too large. 

When you use the Lua C API, you are responsible for eontrolling staek overflow. 
Whenever Lua ealls C, it ensures that at least lua_minstack positions are available, so 
that you only have to worry about staek space when your code has loops pushing 
elements onto the staek. The API offers a number of funetions for basio staek 
manipulation, inoluding 

• void lua_settop. Sets the staek top. 

• void lua_pushvalue. Pushes onto the staek. 

• void lua_remove. Removes element at given position. 

• void lua_insert. Moves top element into given position, shifting elements on top 
of that position to open spaoe. 

• void lua_replace. Replaoes a given element. 

You oan also query the staek with a number of funetions that oheck the type of the given 
objeot and return strings. These funetions inolude the following: 

lua_type 

lua isnil 

lua_isboolean 

lua_isnumber 

lua isstring 

lua_istable 

lua isfunction 

lua_iscfunetion 

lua_isuserdata 

lua_islightuserdata 


lua_equal and lua_rawequal are functions for oomparing two values on the staek. 

To push C values onto the staek, there are a number of funetions that reeeive C values, 
convert them to eorresponding Lua values, and push the resuit onto the staek. These 
include: 

lua pushboolean 

lua pushnumber 

lua pushlstring 

lua pushstring 

lua pushnil 

lua pushcfunction 

lua pushlightuserdata 


When chunks are called, functions like lua-dowhile push onto the staek any values 
eventually returned by the chunks. A chunk can return any number of values, and Lua 
checks to make sure the values fits within the staek space. But after the call, the 
responsibility for fitting within the staek falis back to the programmer. This means that 
if you need to push other elements after calling any of these functions, you should check 
the staek space and remove returned elements from the staek if you do not need them. 
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Garbage Collection 

Lua uses two variables to control its garbage collection cycles. The first keeps track of 
how many bytes of dynamic memory Lua is using. The second variable is a threshold 
that, when hit, telis Lua to run the collector. These are accessible and changeable via the 
C API and through the gcinfo and collectgarbage functions. 

Lua first counts the amount of memory it is using. If the count reaches the threshold, it 
runs the garbage collector. After the collection, the count is updated and the threshold is 
reset to twice the count value. The current count value can be retrieved with 

lua_getccount (lu_State *L); 

The current threshold can be retrieved with 

lua getcthrechold (lua_State *L); 

Each returns their values in KB. The threshold can be changed with 

lua setgcthreshold (lua_State *L, int newthreshold); 

A garbage collection cycle can be forced with 

long lua_collectgarbage(lua State *L long limit); 


This also returns the number of objects collected. 

Garbage collector metamethods for userdata can be also set using the C API. These 
metemethods are called finalizers. The finalizers allow you to coordinate Lua's garbage 
collection with extemal resource management if necessary. 

Speed 

Lua supports coroutines as independent threads of execution. This isn't, however, a true 
independent multi-threaded System—it is a semi-collaborative multithreading system. 
That means a coroutine only suspends its execution by explicitly calling a yield routine. 
Lua also offers some support for multiple threads of execution via its C API, so if you 
have C libraries that offer kicking, then multi-threading Lua can cooperate with them. 

Although garbage collection can be monitored and controlled, the main cause of low 
System performance is a large number of objects generated. If you are managing many 
objects, then the GC is an option, but it may not be always necessary. 

Local variables in Lua are much quicker than global variables. This is because the locals 
are accessed by index. If possible, make any global variables local. Additionally, local 
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variables are kept on the stack and so will not affect the garbage collector (their values 
do not need to be collected by the garbage collector, as they are created on the stack). 

for loops in Lua have been optimized, and also have specialized virtual machine 
instructions. This means that they can be faster than while- and repeat-type loops and 
should be used if speed is your goal. 

The built-in debugger features (mainly hooks) can be used to profde Lua code and look 
for bottlenecks in execution time. There is also a Lua Profiler available on the lua- 
users.org site Wiki page, at http://lua-users.org/wiki/LuaProfder . 

When reading in files, Lua buffers the files in chunks, which is faster than reading files 
line by line. 
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Summary 

Before moving on to the next chapter, you should have Lua installed on your computer 
and you should feel quite eomfortable plugging ehunks into the Lua interpreter. You 
should have taken a good look at Lua's struetures, partieularly if/for/while, and 
espeeially tables. You should have tried playing with a few funetions from the string 
and math libraries. Important points from this ehapter: 

• Lua is normally executed by a host program or language. 

• Lua eode is broken up into ehunks, whieh are similar to program bloeks or 
single statements. 

• Tables are very important in Lua. 

• Lua is not designed for building huge programs. Its aim is to be useful in 
ereating small programs or parts of a larger system. 
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Questions and Answers 


1: Q: What about all the object-oriented features of Lua, like multiple 
inheritance and polymorphism? 

A: A: Although Lua has worked towards OOP support, the language isn't really 
meant to be the huge factory-like mechanism for building giant programs. 
Unlike other OOP-type languages, Lua is meant to be small and flexible. 
Beeause of this, some OOP eonstruets may feel like haeks to the power 
Smalltalk developer. For this reason, I left out some of the eomplieated OOP 
features in this ehapter. 

2: Q: I want to know more about the Lua C API. 

A: A: Start reading the next ehapter! 
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Exercises 


1: List four things tables are used to create in Lua. 

2: Explain the difference between lua.exe and luac.exe. 

3: Explain the concept of "chunks" in Eua. 

4: Write a quick Eua program that looks for and finds white space within a text 
string and then deletes it (bonus points!). 
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Chapter 7. Getting Specific with Games in Lua 


The plainest sign of wisdom is a continual cheerfulness: her state is like that of things in 
the regions above the moon, always elear and serene. 

-Miehel de Montaigne 

In this ehapter, you'll push the boundaries of Lua and examine game programming 
itself—^with some help from LuaSDL. TU also launeh into the Lua C API in this ehapter. 
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LuaSDL 


LuaSDL is Simple DirectMedia Layer's binding into the Lua universe. LuaSDL has its 
own projeet page on Soureeforge, at http://soureeforge.net/proieets/luasdl/ . Lua users 
also keep a copy of the distribution on their Wiki pages, at 
http ://luausers. or g/ wiki/LuaModuleLuaS dl . 

You ean also find a copy of LuaSDL in the Chapter 7 section of this book's CD. The 
LuaSDL binaries are taken from Lua users.org and precompiled and generated by 
Thatcher Ulrich, a programmer for Oddworld Inhabitants. Thatcher's latest LuaSDL 
versions ean be found at his Website, at http://tulrich.com . 

In Windows, you need to place the prebuilt luaSDL.dll somewhere in your path in order 
for SDL to function. The easiest way to do this is to drop the luaSDL.dll into your 
Windows System folder. Linux-platform users also need to set the path or place 
libluaSDL.so into their library-loading path file (which varies; usually usr/lib or 
usr/local/lib). Only the pre-built binaries are available at the time of this writing, and 
they are only available on these platforms. 

NOTE 

TIP 

If you really want to get up-to-speed with SDL, check out the highly rated Focus on 
SDL, by Ernest Pazera, published by Premier Press. 
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Gravity: A Lua SDL Game 


I first introduced SDL way back in Chapter 4, where you used it with Python to do 
some pretty amazing stuff. Lua's SDL bindings aren't quite as complete, and 
unfortunately they are also a little out-of-date. The bindings are stili in beta (Version 0.3 
as of this writing) and were put together using the Lua 4 interpreter (the binary module 
has been pre-packaged with the toLua tool). Because of this, all of the necessary Lua 
Scripts are bundled with the game inside the folder (so you don't try running it with Lua 
5). 

LuaSDL comes bundled with a 2D sprite game prototype called Meteor Shower. The 
game is written entirely in Lua and SDL by Thatcher Ulrich, who has generously given 
the source code to the public domain. I use this code as a base for Gravity. The entire 
source sample can be found in the Gravity folder in the Chapter 7 section on the CD, 
along with the pre-compiled DLLs necessary to use SDL and the Lua 4 interpreter. 

You can launch Gravity from the command line; just navigate to the directory using the 
command line and type: 

Lua Gravity.lua 


In Gravity, the player is the moon in a universe gone haywire. Planetary objects and 
space travelers zoom across the screen, each attracted to themselves and to the player by 
their given mass (see Figure 7.1). The player must avoid these objects or face 
destruction. 


Figure 7.1. Gravity goes haywire in this LuaSDL game 



A number of functions keep Gravity going. The list of functions for Gravity is shown in 
Figure 7.2. 
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Figure 7.2. The function list for Gravity 


shw.sprile 

sprite 


\«c2_nonnailze 


render.frame 

enghe.lnlt 

engine.loop 

ga/Tieloop_iteration 

update.tick 

hande.event 

hande.collsloo 


cursor 

cursor.jpdate 


Sprite functions 
Vector funcBons 


Engine functions 


Cursor functions 


actor 

actor.render 

aclor.update 


hfln(le_player_colision 

piayer.manager 

pia!^r_manager.ren(tor 

piay«r_manager_update 

piay«r_updale 

pteyer 


otetade 

picK_obstacle_lmage 

obstade.take.damage 

hande.obstade.collision 

obstade.update 

otetade.creator 


Actor functkxts 


Player functions 


Obstacte functions 


Importing SDL 

Before other code can start working, the program must have access to LuaSDL. This 
can be achieved with only a few short lines: 

-- Need to load the SDL module 
if loadmodule then 

loadmodule("SDL") 

end 


NOTE 

Lua 5 versus Lua 4 

Lua 5.0 was released early in April of 2003. A number of new features eame with Lua 
5.0, ineluding the following: 

• Coroutines for exeeuting many independent threads. 

• Block eomments for having multiple eomment lines in eode. 

• Boolean types for true and false. 

• Changes to how the API loads ehunks. This is supported by new eommands: 

lua_load, luaL_loadfile, and luaL_loadbuffer. 

• Lightweight userdata that holds a value and not an objeet. 

• Weak tables that assist with garbage eolleetion. 

• A faster virtual maehine that is register-based. 

• Standard libraries that use namespaees, although basic funetions are stili global. 

• New methods of garbage eolleetion, sueh as metamethods and other new 
features that make eolleetion safe. 
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Along with the added features came a number of incompatibilities with previous Lua 
versions. Watch out for the following differenees if you are a Lua 4.0 guru moving to 
Lua 5.0: 

• Metatables have replaeed the tag-method seheme. 

• There are a number of ehanges to funetion ealls. 

• There are new reserved words (ineluding false and true). 

• Most library functions are now defined inside Lua tables. 

• iua_pushuserdata is depreeated and has been replaeed with iau_newuserdata 
and lua pushlightuserdata. 

Work on 5.1 has already begun, and the rumor mill has it that this next version may be 
available by the end of 2003. 

Setting Initial Variables 

You must initialize a blit surfaee and a start gamestate early on for this 2D game. 

Blitting, as you may reeall from Chapter 4, is basieally rendering or drawing, and in 
particular is the act of redrawing an object by eopying the pixels of an object onto the 
screen. 

An SDL blit surfaee looks like this: 

SDL.SDL_BlitSurface = SDL.SDL_UpperBlit; 


The gamestate is a eollection of state variables, assigned to a Lua table, that are 
initialized before the game starts to run. These are listed in Table 7.1. 


Table 7.1. The gamestate Variables 


Element 

Value 

last update ticks 

0 

begin time 

0 

elapsed ticks 

0 

frames 

0 

update period 

30 

active 

1 

new actors 

Nested table 

actors 

Nested table 

add actor 

Funetion 

gamestate = { 



last_update_tick;s = 0, 
begin time = 0, 
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0 , 


elapsed_tick;s = 
frames = 0, 

update period = 30, -- interval between calls to 

update_tick; 

active = 1, 
new_actors = {}, 
actors = {}, 

add_actor = function(self, a) 
assert(a) 

tinsert(self.new_actors, a) 

end 

} 


In this table there are a number of variables set to 0 and also a few nested tables. The 
update_period is the interval in milliseeonds between calls to the update tick, and 
active is a Boolean that says whether the engine is currently active or not. The 
add_actor function is also defined in this table. 

The next Lua table is for a sprite cache. This cache will hold sprites that have already 
been loaded, so the engine won't have to try and load them on-the-fly: 

sprite_cache = {} 


Gravity is all about speed and velocity and, well, gravity. I envisioned flying planetary 
objects, each with different masses, bumping and colliding with each other in a solar 
system-like playing screen. To achieve this effect, I have to set gravity, how often 
obstacles fly onto the screen, and how many lives the player will have. 

-- Set gravity 
GRAVITY_CONSTANT = 100000 

-- table of Virtual masses for the different obstacle sizes 
obstacle_masses = { 10, 50, 75 } 

OBSTACLE_RESTITUTION = .05 
-- Soft speed-limit on obstacles 
SPEED_TURNOVER_THRESHOLD = 4000 
-- player manager actor 
MOONS_PER_GAME = 3 

--How often till new obstacle appears 
BASE RELEASE PERIOD = 500 


The three obstacles, two planets and a space cow, are illustrated in Figure 7.3. Each will 
use a unique bitmap image that is already included in the Gravity folder. These images 
are placed into a Lua table. 

Figure 7.3. The three obstacles in Gravity 
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--load the bitmap obstacle images 
obstacle_images = { 

{ "obstaclel.bmp" }, 

{ "obstacle2.bmp" }, 

{ "obstacle3.bmp" }, 

} 


Creating Functions 

Creating functions is really the meat and gravy of the endeavor. You need funetions, 
lots of functions. Sprites, vectors, events, the game engine, and each actor (or object) 
within the game must be handled. 

Sprite Handling 

Sprite handling is the first thing to taekle (see Figure 7.4). The main sprite function will 
be a eonstructor that takes in a bitmap file and returns an SDL surfaee that ean be blitted 
and used by the engine. A funetion that draws the new blitted SDL surfaee sprite onto a 
rect (rects are again from Chapter 4—they are the basie object for a 2D SDL game) 
will be part of the proeess as well. The main sprite function will be sprite (): 

Figure 7.4. Sprite handling functions in Gravity 
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V 


SDL surface is passed 
to the 8how_sprite 
function 


5how_Bprtte 


Ensurea tamporery 
rect structure 


function sprite(file) 

-- The sprite constructor. Passes in a bitmap filename and returns an 
SDL_Surface 

--First check the cache 
if sprite cache[file] then 

return sprite_cache[file] 

end 

local temp, my_sprite; 

-- Load the sprite image 
my sprite = SDL.SDL LoadBMP(file); 
if my_sprite == nil then 

print("Couldn't load " .. file .. " .. 

SDL.SDL_GetError()); 

return nil 

end 

-- Set colorkey to black (for transparency) 

SDL.SDL_SetColorKey(my_sprite, SDL.bit_or(SDL.SDL_SRCCOLORKEY, 
SDL.SDL_RLEACCEL), 0) 

-- Convert sprite to video SDL format 
temp = SDL.SDL DisplayFormat(my sprite); 

SDL.SDL_FreeSurface(my sprite); 
my_sprite = temp; 

sprite_cache[file] = my_sprite 
return my sprite 

end 


The sprite eonstruetor first eheeks to make sure that the sprite doesn't already exist in 
sprite cache. If it does not, the eonstruetor tries to find the given BMP image file. If 
the file doesn't exist, the eonstruetor exits with an error; otherwise it goes ahead and 
loads the image into an SDL format (using a temp variable as interim), sets the 
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colorkey (another Chapter 4 concept), loads the sprite into the sprite_cache, and 
returns the sprite. 

The seeond sprite funetion, show sprite, is passed a sprite and draws it on the sereen 
at the given eoordinates (x,y). It uses the massively powerful rect () to aeeomplish this. 
Notiee that in order for show_sprite to work, it needs all four variables: 

funetion show_sprite(sereen, sprite, x, y) 

-- make sure we have a temporary reet strueture 
if not temp reet then 

temp reet = SDL.SDL Reet new() 

end 

temp reet.x = x - sprite.w / 2 
temp_reet.y = y - sprite.h / 2 
temp reet.w = sprite.w 
temp reet.h = sprite.h 

SDL.SDL_BlitSurfaee(sprite, NULL, sereen, temp reet) 

end 

Vector Handiing 

When used in game physies, vectors combine magnitude (speed) and direction (see 
Figure 7.5). Vectors are extremely useful, as the engine needs to know the speed and 
direction of the objects and actors flying around the sereen. In order to do this, the vee2 
funetion needs to take in a table and do some math. 

Figure 7.5. Vectors in physies combine magnitude and direction. 



In geometry, vectors consist of a point or a location in space, a direction, and distance. 
The combination of direction and distance is sometimes called displacement. The vec2 
funetion helps to keep track of vectors using x and y eoordinates, as shown in Figure 
7.6. The starting eoordinates are a. x and a. y, and the ending eoordinates are b. x and 

b.y. 
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Figure 7.6. Starting and endingpoints ofa vector 



The V 0 c 2 function hcis 3. miiiiber of rnethods for determiniii^ speed 3nd direction of 3ii 
actor or object using vectors. The add, sub, mui, and unm rnethods are used to track 
position in two-dimensional space by performing sector arithmetic. 

The add method is used to do vector addition where the results of two vectors can be 
plotted in two-dimensional space, as shown in Figure 7.7. Vector subtraction is handled 
by the sub method, and does the opposite of vector addition by delivering the difference 
between two vectors. 


Figure 7.7. Vector addition 
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You can multiply a vector by a constant to produce a second vector that travels in the 
same or the opposite direction but at a different speed. Multiplying vectors in math is 
called scalar multiplication. Scalar multipication can be really useful for collisions—say 
if two planets in the Gravity game collide, and they need to bounce off of each other in 
opposite directions. 

There is also a second way of multiplying vectors that gives the angle between two 
vectors. This called the dot product; it is also handled by the mul method. Although you 
don't use the dot product in this game, it is a useful vector function and is sometimes 
used to perform lighting calculations (say, if you wanted to add a sun object that casts 
shadows to the game) or determine facing in 3D games. 


After running through vec2, vec2_normalize finishes the vector math by dividing by 
the length and catching any possible close to 0 calculations that could cause errors. 


--vec2 tag = nil 

-- re-initialize the vector type when reloading 
function vec2(t) 

-- constructor 

if not vec2_tag then 

vec2_tag = newtagO 

Vector addition 

settagmethod(vec2_tag, "add", 

function (a, b) return vec2{ 


b.y } end 


a.x + b.x, a.y + 
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b.y } end 


Vector subtraction 
settagmethod(vec2_tag, "sub", 

function (a, b) return vec2{ a.x - b.x, a.y - 


} 

} 


b.y) 


) 

Vector multiplication 
settagmethod(vec2_tag, "mul", 
function (a, b) 

if tonumber(a) then 

return vec2{ a* b.x, a* b.y 

elseif tonumber(b) then 

return vec2{ a.x*b, a.y*b 


-- dot product. 

return (a.x * b.x) + (a.y * 


end 


end 


settagmethod(vec2_tag, "unm", 

function (a) return vec2{ -a.x, -a.y } end 


end 


end 


local V = {} 

if type(t) == 'table' or tag(t) == vec2_tag then 
v.x = tonumber(t[1]) or tonumber(t.x) or 
v.y = tonumber(t[2]) or tonumber(t.y) or 

else 


v.x = 0 
v.y = 0 

end 

settag(v, vec2_tag) 
v.normalize = vec2 normalize 
return v 


0 

0 


function vec2 normalize(a) 

-- If a has 0 or near-zero length, sets a to an arbitrary unit vector 
local d2 = a * a 
if d2 < 0.000001 then 


-- Return arbitrary unit vector 
a. X = 1 
a. y = 0 

else 

-- divide by the length to get a unit vector 
local length = sqrt(d2) 
a.x = a.x / length 
a.y = a.y / length 

end 

end 


Event Handling 

Handlers for key presses and mouse elieks are neeessary for any eomputer game. Mouse 
events will be pieked up by the individual aetor that Controls the player, but monitoring 
for the keyboard and Windows events must also occur in case a player wants to close a 
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window or quit using the Escape key. This can be done fairly easily (see Figure 7.8) by 
using SDL_KEYDOWN to watch for SDLK_q or SDLK_ESCAPE. 


Figure 7.8. Event handling 



function handle_event(event) 

-- called by main loop 
--Checks for keypresses 

-- sets gamestate to nil if player wants to quit 
if event.type == SDL.SDL_KEYDOWN then 

local sym = event.key.keysym.sym 

if sym == SDL.SDLK_q or sym == SDL.SDLK_ESCAPE then 
gamestate.active = nil 


end 

elseif event.type == SDL.SDL_QUIT then 
gamestate.active = nil 

end 


end 


The Engine and the Game Loop 

A number of actions must happen in the engine and game loop, and these aetions should 
eorrespond to a eodeable function. You must have a function to remove any sprites that 
aren't being used and add any new ones, a function to render the screen and background, 
a function that keeps track of time and updates the game state, a function that does the 
blitting, and a function that listens for player keystrokes: 

• render_frame. Updates and redraws. 

• engine_init, Sets screen and video. 

• engine_loop. Main engine loop. 

• gameloop_iteration, Tracks time and call other functions. 

• update_tick, Updates any game actors. 

• handle_event. Listens for any events caused by the player. 

• handle_collision. Handles any actor collisions. 

The first step is to initialize the engine. 
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The engine_init function is used to set the screen width and height and the video 
mode and to start the game ticking, so to speak. It does all this through common-sense 
loeal variables, a few SDL calls, and calling gamestate: 


function engine init(argv) 

loeal width, height; 
loeal video_bpp; 
loeal videoflags; 

videoflags = SDL.bit_or(SDL.SDL_HWSURFACE, SDL.SDL_ANYFORMAT) 

width = 800 

height = 600 

video_bpp = 16 

-- Set video mode 

gamestate.screen = SDL.SDL SetVideoMode(width, height, 
video_bpp, videoflags); 

gamestate.background = SDL.SDL MapRGB(gamestate.screen.format, 

0 , 0 , 0 ); 

SDL.SDL_ShowCursor(0) 

-- initialize the timer/ticks 

gamestate. begin time = SDL.SDL GetTicksO; 

gamestate.last update ticks = gamestate.begin time; 

end 


Removing any actors that are no longer used and adding any new aetors is handled by 
an update_tick funetion. Two Lua for loops iterate through eaeh aetor in the game. 
The first removes any aetors that aren't aetive and adds any new ones: 

for i = 1, getn(gamestate.actors) do 

if gamestate.actors[i].active then 
-- add the actors 
tinsert(gamestate.new_actors, 

gamestate.actors[i]) 
end 

end 


The former gamestate. actor table is then replaeed with the new table in a quiek swap; 

gamestate.actors = gamestate.new_actors 
gamestate.new_actors = {} 


Then a seeond for loop calls an update for eaeh actor in the table: 

-- call update for eaeh actor 

for i = 1, getn(gamestate.actors) do 

gamestate.actors[i]:update(gamestate) 

end 


After the actors have been updated, eaeh needs to be redrawn, as does the screen. A 
quiek render_frame function docs this work, first clearing the current screen and then 
redrawing eaeh actor rect () within gamestate. actors: 

function render frame(screen, background) 
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-- When called renders a new frame. 

-- First clears the screen 

SDL.SDL FillRect(screen, NULL, background); 
-- re-draws each actor in gamestate.actors 
for i = 1, getn(gamestate.actors) do 

gamestate.actors[i]:render(screen) 

end 

-- updates 

SDL.SDL_UpdateRect(screen, 0, 0, 0, 0) 

end 


Most of the actual game-engine work is done by this next little function, called 
gameloop_iteration. It is called cach time the engine loops, and is responsible for 
calling all the other rendering functions and keeping track of time. First 
gameloop_iteration calls handle_event on any pending cvcnts in the gamestate's 
event_buffer (checking first that the buffer exists): 

function gameloop_iteration() 

-- call this to update the game state. Runs update ticks and renders 
-- according to elapsed time. 

-- if buffer doesnt exist make it so 
if gamestate.event buffer == nil then 

gamestate.event buffer = SDL.SDL_Event new() 

end 

-- run handle even on any pending events 

while SDL.SDL_PollEvent(gamestate.event_buffer) ~= 0 do 

handle event(gamestate.event buffer) 

end 


gameloop iteration then USeS SDL GETTICKSO tO SCt the local time variablc and 
compares this with the gamestate to see if an update needs to occur. If the engine needs 
to update, then update_tick is called and the time count is updated: 

-- run any necessary updates 

local time = SDL.SDL GetTicksO; 

local delta_ticks = time - gamestate.last update ticks 
local update_count = 0 

while delta_ticks > gamestate.update period do 
update_tick() ; 

delta_ticks = delta_ticks - gamestate.update_period 
gamestate.last_update_ticks = 
gamestate.last_update_ticks + 
gamestate.update_period 

update_count = update_count + 1 

end 


Finally, render_f rame has to be callcd to redraw any actors and the screen background 
if an update has occurred; 

-- if we did any updates, then render a frame 
if update count > 0 then 

render frame(gamestate.screen, gamestate.background) 
gamestate.frames = gamestate.frames + 1 

end 
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end 


The actual engine game loop (engine_loop) runs while the gamestate is active. The 
engine loop Calls gameloop iteration cach time its OWn while loop flrcs. The 
engine_loop then clcans out the buffer. If the gamestate is no longer active, then 

engine loop calls SDL QUIT: 


function engine loopO 

-- While loop calls gameloop iteration 
while gamestate.active do 

gameloop iteration() 

end 

-- clean up 
if event buffer then 

SDL.SDL Event delete(event) 

end 

SDL.SDL_Quit 0; 

end 


Actors 

Everyone wants to be an actor—or a computer game programmer—these days. Actors 
in Gravity aren't as revered or lucky as the Hollywood variety, however. They are the 
constructs that can be interacted with in the game, as shown in brief in Figure 7.9. These 
base actor functions will be used by the other objects in the game. 

Figure 7.9. Actors are initializedin Gravity 



Learning how to update an actor's position on the screen is the first task here, and this is 
where the vector functions get to stretch their legs. Velocity is multiplied by how much 
time has elapsed in the gamestate loop since the last update: 
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function actor_update(self, gs) 

-- Updates than actor using vector functions 

local dt = gamestate.update_period / 1000.0 
-- update according to velocity & time 
local delta = self.velocity * dt 
self.position = self.position + delta 


Since this is a 2D Asteroids-type game, objects on the screen should wrap around to the 
other side when they hit an edge. This effect is achieved with simple math applied to the 
position and the game screen (gs. screen) before actor_update ends: 


-- wrap around at screen edge 

if self.position.X < -self.radius and self.velocity.x <= 

then 


self.position.X = self.position.x + (gs.screen.w 

self.radius * 2) 
end 

if self.position.X > gs.screen.w + self.radius and 
self.velocity.X >= 0 then 

self.position.X = self.position.x - (gs.screen.w 

self.radius * 2) 
end 

if self.position.y < -self.radius and self.velocity.y <= 

then 


self.position.y = self.position.y + (gs.screen.h 

self.radius * 2) 
end 

if self.position.y > gs.screen.h + self.radius and 
self.velocity.y >= 0 then 

self.position.y = self.position.y - (gs.screen.h 

self.radius * 2) 
end 


0 

+ 


0 


+ 


end 


A function that blits actors onto the screen using show_sprite is the next thing to 
create after determining the actor's position: 

function actor render(self, screen) 

-- Blit the given actor to the given screen 

show_sprite(screen, self.sprite, self.position.x, 
self.position.y) 
end 


The final curtain on actors is to build an actor constructor. The constructor will take in 
the sprite bitmap and keep track of position, velocity, and radius, and then return the 
actor in a nice, neat Lua table: 

function actor(t) 

-- actor constructor. Pass in the name of a sprite bitmap. 
local a = {} 

-- copy elements of t 
for k,v in t do 
a[k] = V 

end 
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nil 


end 


a.type = "actor" 
a.active = 1 

a.sprite = (t[l] or t.sprite and sprite(t[l] or t.sprite)) or 


a.position 
a.velocity 
a.radius = 
or 
or 


= vec2(t.position) 

= vec2(t.velocity) 
a.radius 

(a.sprite and a.sprite.w * 
0 


a.update = actor_update 
a.render = actor render 
return a 


0.5) 


Obstacles 

The game obstacles are cows and planets. These obstacles must track a number of 
different things in order to make the game interesting. 

• Obstacles can take damage. Some of the bigger objects will survive colbsions 
with several smaller objects, so they need to track how much damage they can 
take. 

• Obstacles need to know when they collide with something. 

• Obstacles are drawn to each other by gravity, and so they need to keep track of 
other nearby obstacles. 

Obstacles should also occasionally appear on the screen. They should come firom 
offscreen at a random place, at a random speed, and travel somewhat towards the center 
of the screen. These object capabilities are handled with the following functions: 

• obstacle_update(), Handles gravity, movement, and colbsions. 

• handle_obstacle_collision(), Called when a collision is detected. 

• obstacle_take_damage(). Damages the object. 

• pick_obstacle_image(). Chooses one of the obstacle images at random. 

• obstacleQ, The obstacle constructor. 

• obstacle_creator(). Randomly places obstacles onto the screen. 

The obstacle_update is the first function to tackle. It watches for colbsions by first 
updating itself and then keeping track of where the other actors are: 

function obstacle_update(self, gs) 

-- update this obstacle. watch for collisions with other actors. 

-- move ourself 
actor_update(self, gs) 

local dt = gamestate.update_period / 1000 
local accel = vec2() 

-- check for the position of other actors 
for i = 1, getn(gs.actors) do 

local a = gs.actors[i] 


Actors with a large mass will draw other actors towards themselves. This is simulated 
with the GRAVITY_C0NSTANT, thc two actors' mass, and some math. 
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The Newtonian concept of attraction takes the mass of two objects, the distance between 
them, and the constant of gravity to determine how strong the attraction is between the 
two objects (see Figure 7.10). 

Figure 7.10. Newton’s law of attraction (i.e. universal gravitation) 



This law is usually expressed by (G*ml)*(G*m2)/r^2, where G is the gravitational 
constant, ml is the mass of the first object, m2 is the mass of the second object, and r is 
the distance between the two objects. 

This formula is used in obstacle_update by taking the gravity_constant and the 
mass of an object (a. mass) and accelerating actors towards other actors: 


-- if the actor has mass then compute a gravitational acceleration 
towards it 

if a.mass then 

local r = a.position - self.position 
local d2 = r * r 
if d2 < 100 * 100 then 

local d = sqrt(d2) 

if d * 2 > self.radius then 

accel = accel + r * ((GRAVITY CONSTANT 


a.mass) / (d2 * d) ) 


end 


end 


end 


■k 


Then obstacle_update nceds to check for actual collisions and handle them by calling 
handle_collision. You cnd thc function by resetting the actor's velocity: 

-- check for collisions, and respond 

if a and a ~= self and a.collidable then 
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self.radius) 


2 


local disp = a.position - self.position 
local distance_squared = disp * disp 
local sum_radius_squared = (a.radius + 


collision handler. 


end 

end 

self.velocity 

end 


if distance squared < sum radius squared then 
-- we have a collision, call the 

handle collision(self, a) 

end 


self.velocity + accel * dt 


The next function, handie_obstacie_coiiision, fires when the obstacles collide. It 
first makes sure that the collision is between two obstacles and not between an obstacle 
and the player; that would be handled by a different function. It then damages the 
objects that collide by calling obstacle_take_damage: 

function handle obstacle collision(a, b) 

-- handles a collision between two obstacles, a and b. 

--Make sure we are handling collison between two obstacles, 
otherwise exit 

if a.type == "obstacle" and b.type == "obstacle" then 

-- impulse will be along the displacement vector between 
the two obstacles 

local normal = b.position - a.position 
normal:normalize() 

local relative vel = b.velocity - a.velocity 
-- Damage the objects that collide 
local collision-energy =0.1 * (relative vel * 
realtive_ve;) * (a.mass + b.mass) 

local split dir = vec2{ normal.y, -normal.x } 
obstacle take damage(a, split dir, -normal, 
collision energy) 

obstacle_take_damage(b, split dir, normal, 
collision energy) 
end 

end 


The obstacle_take_damage is callcd in the evcnt of a collision. Some objects may 
survive a collision, but at least one (the one with lesser mass) will be destroyed. The 
smallest objects (cows) will always be destroyed; 


function obstacle take damage(a, split direction, collision normal, 
collision energy) 

-- damage the obstacle; if it's damaged enough, destroy 

local split_speed = sqrt(2 * collision_energy / a.mass) * 0.35 
-- obstacle takes damage; when its damage reaches 0 it dies 
a.hitpoints = a.hitpoints - collision energy / 2000 
if a.hitpoints > 0 then 

-- collision is not violent enough to destroy this 


obstacle 


end 


return 
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1 


local new_size = a.size - 
if new size < 1 then 

-- The smallest obstacle always disintegrates. 

a.active = nil 

return 

end 

-- kill a 
a.active = nil 

end 


Pick_obstacle_image is a short random function that will pick which object to use 
from the image_table using Lua's built-in random: 

function pick obstacle image(size) 

local image table = obstacle images[size] 

-- pick one of the obstacle images at random 
return image_table[random(getn(image_table))] 

end 


The obstacle constructor uses the actor eonstructor as its building block. It then sets 
its type to "obstacle", flags it as eollideable, makes sure it has one of the three 
obstacle sizes, and then sets variables for radius, size, and speed. It also assigns the 
obstacle to obstacle_update: 


-- constructor 

-- start with a regular actor 
local a = actor(t) 
a.type = "obstacle" 
a.collidable = 1 

a.size = a.size or 3 -- make sure caller defined one of the 

three sizes of obstacle 

a.sprite = sprite(pick_obstacle_image(a.size)) 
a.radius = 0.5 * a.sprite.w 
a.mass = obstacle_masses[a.size] 
a.hitpoints = a.mass * a.mass 

-- implement a speed-limit on obstacles 
local speed = sqrt(a.velocity * a.velocity) 
if speed > SPEED_TURNOVER_THRESHOLD then 

local new_speed = SPEED_TURNOVER_THRESHOLD + 

sqrt(speed - 

SPEED_TURNOVER_THRESHOLD) 

a.velocity = a.velocity * (new_speed / speed) 

end 

-- attach the behavior handlers 
a.update = obstacle_update 
return a 

end 


Math functions like sqrt () have a reputation for being slow, especially when complex 
math has to be calculated on-the-fly. Having to process sudden large computations can 
cause an otherwise fluidly running game to grind to a halt. One way to speed up sqrt is 
to cache any square root values that are used more than once. Lef s say you had the 
following code: 
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a* sqrt(s) 
b* sqrt(s) 
c = a+b 


Instead of running the sqrt () function twice, run it once first and store the value: 

square = sqrt(s) 
a*square 
b*square 
c = a+b 


A second trick is to do common math ahead of time and place it in a table for the 
program. Lef s say you did a log of power of multiplication in a program; you could 
work out common equations first and put them in a table like Table 7.2. 


Table 7.2. Common Power 


Initial Value 

A2 

^3 

2 

4 

8 

3 

9 

27 

4 

16 

64 

5 

25 

125 

6 

36 

216 


When the code needs one of these values, it gets a reference to the appropriate row and 
column instead of calculating on-the-fiy. 

The very last thing obstacles need to do is appear occasionally on the screen to harass 
the player. This is achieved by creating an actor that sets a countdown timer. When the 
timer reaches 0, the actor calls the obstacle construet, creates the obstacle on the edge of 
the screen, and sets it fiying towards the middle somewhere. Then it starts the timer 
over again: 

-- random obstacle creator 
function obstacle_creator(t) 

-- constructs an actor that randomly spawns a new obstacle 
periodically 

a = {} 

a.active = 1 

a.type = "obstacle_creator" 
a.collidable = nil 
a.position = vec2{ 0, 0 } 

a.velocity = vec2{ 0, 0 } 
a.sprite = nil 

-- set the random timer countdown 

a.period = t.period or t[0] or 100 -- period between 

spawning obstacles 

a.countdown = a.period 
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a.render = function () end 
a.update = 

function (self, gs) 

self.countdown = self.countdown - 


gs.update_period 

obstacle 
of the screen 


if self.countdown < 0 then 

-- timer has expired; spawn an 

-- pick a random spot around the edge 


local w, h = gs.screen.w, gs.screen.h 
local edge = random(w * 2 + h * 2) 
local pos 
if edge < w then 



pos 

= 

vec2 { 

edge, 0 } 


elseif 

edge 

< 

w*2 then 




pos 


vec2 { 

edge - w. 

h } 

elseif 

edge 

< 

w*2 + 

h 

then 



pos 


vec2 { 

0, 

edge - 

w*2 } 

else 

pos 


vec2 { 

w. 

edge - 

(w*2 + 


end 

-- aim at the middle of the screen 
local vel = vec2{ w/2, h/2 } - pos 
vel:normalize() 

vel = vel * (random(400) + 50) 
gs:add_actor( 

obstacle{ 

size = random(3), 
position = pos, 
velocity = vel 

} 


end 


end 

return a 


end 


-- reset the timer 

self.countdown = self.period 


The Player 

The player is arguably the most important game pieee. Mueh of the infrastrueture the 
player needs (sueh as sprite handling and aetor functions) has already been laid out. 
However, you stili need functions to handle the following: 


• Updating the player 

• Player collision 

• The player constructor 


The player_updater function handles updating the player; it looks similar to the 
object_updater function. The player objcct is handlcd just like an operating system's 
mouse cursor. The playefs position is based on the mouse position. Using 
SDL_GetMouseState, the player position is updated, and checks for any collisions are 
made. If there is a collision, handle_player_collision is called: 
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function player_update(self, gs) 

-- update the player and watch for collisions 

local dt = gamestate.update_period / 1000 
-- get the mouse position, and move the player position 
towards the mouse position 
local m = {} 

m.buttons, m.x, m.y = SDL.SDL_GetMouseState(0, 0) 
local mpos = vec2{ m.x, m.y } 
local delta = mpos - self.position 

local accel = 

delta * 50 -- move towards the mouse cursor 

- self.velocity * 10 -- damping 

self.velocity = self.velocity + accel * dt 
-- move ourself 
actor_update(self, gs) 

-- check for collisions against all other actors 
for i = 1, getn(gs.actors) do 

local a = gs.actors[i] 

-- check for collisions, and respond 
if a and a ~= self and a.collidable then 

local disp = a.position - self.position 
local distance_squared = disp * disp 
local sum_radius_squared = (a.radius + 

self.radius) ^ 2 

if distance squared < sum radius squared then 
-- we have a collision 
-- call the collision handler. 
handle player collision(self, a) 

end 

end 


end 


end 


The handie_piayer_coiiision also looks quite a bit like the 
handie_obstacie_coiiision, except it's shorter beeause there is no eoneem over 
damage. A eollision will kill the player by setting its active method to nil: 

function handle player collision(a, b) 

-- handles a collision between a player, a, and some other object, b 
-- impulse will be along the displacement vector between the 
two obstacle 

local normal = b.position - a.position 
normal:normalize() 

local relative vel = b.velocity - a.velocity 
if relative vel * normal >= 0 then 

-- don't do collision response if obstacles are moving 
away from each other 

return 

end 

-- Kill the player 
a.active = nil 

end 


The player constructor is similar to the other eonstruetors that have been built, exeept 
that it's smaller. The aetor template is used initially, then the eonstruetor loads the 
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moon.bmp as its image, sets itself as collideable, gives itself a mass (yes, the player's 
gravity attracts objects) and radius, and sets itself to run player_update. 

function player(t) 

-- constructor 

-- start with a regular actor 
local a = actor(t) 
a.type = "player" 
a.collidable = 1 

a.sprite = sprite("moon.bmp") -- or error("can't load 
a.radius = 0.5 * a.sprite.w 
a.mass = 10 

-- attach the behavior handlers 
a.update = player_update 
return a 

end 


The player objeet needs a few utility funetions with whieh to keep traek of his lives 
and whether he's entered the game. The player eursor will have different visual States 
before the game starts, while playing, and after a eollision, so these need to be kept 
traek of as well. This is done with eorresponding funetions in the player_manager. 

First is the piayer_manager_update. It keeps track of the player state, whieh is either 
pre-game or setup, aetive or playing, or deeeased. If the player has died, 
piayer_manager_update eheeks to see if there are any lives left by eheeking the 
MOONS_PER_GAME eonstant. If there are, there is a short delay before the player can 
launeh his next moon. These are all handled by a handful of Lua if elseif then 
statements: 

function player manager update(self, gs) 

-- keep track of game funetions 

if self.state == "pre-setup" then 

-- delay, and then enter setup mode, 
self.countdown = self.countdown - 
gamestate.update_period 

if self.countdown <= 0 then 
self.state = "setup" 
self.cursor.active = 1 
gamestate:add_actor(self.cursor) 

end 

elseif self.state == "setup" then 

if not self.cursor.active then 

-- player has placed the moon. start playing. 
self.player.active = 1 

self.player.position = self.cursor.position 
gamestate:add_actor(self.player) 

-- deduct the moon that we just placed. 
self.moons = self.moons - 1 
self.state = "playing" 

end 

elseif self.state == "playing" then 

if not self.player.active then 
-- player has died. 
if self.moons <= 0 then 
-- game is over 
self.state = "pre-attract" 
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self.countdown = 1000 

else 

-- set up for next moon 
self.state = "pre-setup" 
self.countdown = 1000 

end 

end 

elseif self.state == "pre-attract" then 

-- delay, and then enter attract mode 
self.countdown = self.countdown - 
gamestate.update_period 

if self.countdown <= 0 then 

self.state = "attract" 


end 

elseif self.state == "attract" then 
local m = {} 

m.buttons, m.x, m.y = SDL.SDL_GetMouseState(0, 
if m.buttons > 0 then 

-- start a new game. 
self.state = "pre-setup" 
self.moons = MOONS PER GAME 


0 ) 


end 


end 


end 


self.countdown = 1000 


The function called player_manager_render comes in at this point to display moon 
sprites that show how many lives the player has left: 


function player manager render(self, screen) 
if self.state == "attract" then 

show sprite(screen, self.game over 

2, screen.h / 2) 
else 


end 


end 


-- show the moons remaining 
local sprite = self.player.sprite 
local X = sprite.w 
local y = screen.h - sprite.h 
for i = 1, self.moons do 

show_sprite(screen, sprite 
X = X + sprite.w 

end 


sprite. 


X, y) 


screen.w / 


The player_manager constructor is the last function you need to wrap up the player. 
Like the eonstruetors, this function builds a Lua table that Stores the variable you need, 
such as which player mouse curser you currently use, how many lives are left, and who 
to call for rendering and updating: 

function player manager(t) 

-- constructor 

local a = {} 

for k, V in t do a[k] = v end -- copy values from t 
a.active = 1 

a.moons = MOONS PER GAME 
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a.state = "setup" 
a.cursor = cursor{ 

} 

gamestate:add_actor(a.cursor) 
a.player = player{ 

position = { gamestate.screen.w / 2, 
gamestate.screen.h /2 }, 

velocity = { 0, 0 }, 

} 

a.obstacle creator.period = BASE RELEASE PERIOD 
a.game over sprite = sprite ("finish.bmp") 
a.update = player_manager_update 
a.render = player manager render 
return a 

end 


Starting the Game 

Almost finished! Only a few functions remain. The mouse cursor must be properly 
tracked and you need a check for mouse buttons that will start gameplay. The mouse 
cursor is set initially to a start.bmp graphic that lets the player choose where to position 
the moon when in the playing window. AU of these actions are accomplished with 
cursor_update and the cursor constructor, and all the information is held within Lua 
tables: 


function cursor_update(self, gs) 

-- update the cursor. follow the mouse. 
local m = {} 

m.buttons, m.x, m.y = SDL.SDL_GetMouseState(0, 0) 
self.position.X = m.x 
self.position.y = m.y 
if m.buttons ~= 0 then 

-- player has clicked 
self.active = nil 

end 

end 

function cursor(t) 

-- constructor 

-- start with a regular actor 
local a = actor(t) 
a.type = "cursor" 

a.sprite = sprite("start.bmp") -- or error("can't load ....") 

a.radius = 0.5 * a.sprite.w 

-- attach the behavior handlers 

a.update = cursor_update 

return a 

end 


Initializing the game engine is a pretty straightforward endeavor after all the work thafs 
already been done. The engine_init function is called, and a slew of obstacles are in 

the gamestate with add actor: 

engine init{} 

-- Generate a bunch of obstacles 
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for i 


= 1,10 do 

gamestate:add_actor( 
obstacle{ 

position = { random(gamestate.screen.w) , 
random(gamestate.screen.h) }, 

velocity = { (random()*2 - 1) * 100, 

(random 0*2 - 1) * 100 }, - 

- pixels/sec 

size = random(3) 

} 


end 


Then create an obstacie_creator and a piayer_manager and let them duke it out: 


-- create an obstracle creator 
creator = obstacle_creator{} 
gamestate:add_actor(creator) 

-- create a player manager 
gamestate:add_actor( 

player managerj 

obstacle creator 



creator 


Last but not least, eall the engine_loop (), and lo-and-behold, the game is running: 


-- run the game 
engine_loop() 
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The Lua C API 


Ah, the power of C. Anything that can be done directly in Lua can also be done in the 
Lua C API, including manipulating variables and tables, calling functions, controlling 
the garbage collector, or loading Lua from strings or files. 

Typically, the Lua C library is compiled into an application or run as a shared library. 
This is the most common way of accessing Lua in a game program. Altogether, the Lua 
library is very small, so it is not uncommon to find the entire source tree included with a 
distributed game. 

NOTE 

TIP 

If you want to delve deeper into the C family, check out C Programming for the 
Absolute Beginner, by Michael Vine, or C++ Programming for the Absolute Beginner, 
by Dirk Henkemans and Mark Lee. 

Opening Up Lua 

Before calling any API function, a pointer to the Lua state must be passed as the first 
argument. This pointer opens up Lua. The lua open command (introduced in Chapter 
6) is what fires up the Lua state. AU API functions need to set lua_open up as their very 
first argument. 

In order to use lua open in a C environment, the lua.h file must be included. The lua.h 
file is a C header file that defines the Lua API. However, since Lua is ANSI C, any 
inclusions of the Lua library must be wrapped within an extern C command, otherwise 
the compiler will mangle the names and not be able to call the commands properly. This 
may sound complicated, but in practice it looks like this: 

extern "C" 

{ 

#include <lua.h> 

} 


NOTE 

Name Mangling 

Compilers have a habit of modifying the names of functions and objects when 
compiling. This is done so that the compiler can include extra Information, provide type 
linkage, and support function overloading. This modification is often called mangling. 
Particularly confusing is that each compiler has its own way of mangling names and 
laying out the compiled objects. This can cause problems when working with more than 
one language, as a second language cannot predict how a particular object or command 
may be mangled. Euckily, the extern command can be used to disable name mangling 
entirely. 
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When the Lua state machine is finished with its job, it should be closed using the 
lua_close () command. This command destroys all objects in the given Lua state via 
the garbage eollector. Therefore, a full instanee of Lua wrapped within C code looks 
something like this: 

extern "C" 

{ 

#include <lua.h> 

} 

lua_state *Mylua lua_open (0) 

// Many lines of 
// Useful Lua code that 
// Do something 
lua_close (MyLua) 


More or less, every function in the Lua API deals with the Lua state or the current state 
of the Lua interpreter (you will often hear Lua being referred to as a "state machine" 
when used in this way). The Lua state keeps track of functions, globals, and any 
interpreter-related information. When the Lua state is closed, all the Lua objects and any 
dynamic memory used by the state are freed. 

Whenever Lua calls C, the called function gets a virtual stack. This stack contains any 
arguments to the C function, is used to pass values to and from C, and will hold any 
values the C functions push back. Stacks can hold more than one element and are 
represented by an index, the top element of which can be called with lua_gettop: 

Int lua_gettop (lua_State *L) ; 


NOTE 

On some platforms, you may not need to call the close state, because 
resources are released normally when the program ends. Long-running 
programs or daemons may need to be released occasionally. 


Stack Commands 

Lua uses a stack to pass values to and from C. Each element in this stack represents a 
value (nil, number, and so on) that Eua uses. The Eua API offers a number of useful 
commands for manipulating the stack, querying stack functions, and translating C to 
Eua. These commands are listed and summarized in Table 7.3. 

Stack commands are normally given as arguments to the lua State, a pointer to Eua 
(*Lua), and/or the appropriate index in the stack. Push functions receive a C value, 
convert it to a corresponding Eua value, and then push the resuit onto the stack. 

The Eua stack is is the primary means of communication between C and Eua. There are 
no Eua type values in C, only functions that manipulate the stack. All values, functions, 
and so on are pushed onto or pulled from the stack. 
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Variables 


Lua variables in the API do not need to be declared, and by default are eonsidered 
global in seope unless speeified otherwise. The variables that store Lua values are 
global values, loeal values, or table fields. 

Loeal values ean be deelared anywhere within a bloek or ehunk of Lua eode. They are 
lexieally seoped. This means the seope of variables begins at the first statement after 
their deelaration and lasts until the end of the innermost bloek that ineludes the 
deelaration. 


Table 7.3. Lua APIStack Commands 


Command 

Type 

Purpose 

lua concat (); 

void 

Coneatenates the values at the top of a staek, 
pops them, and leaves the resuit at the top 

lua equal (); 

int 

Compares two items on the staek 

lua_insert (); 

void 

Moves the top element to a given index 

lua isboolean () ; 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua iscfunction (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua isfunction () ; 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua isnil (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua isnumber (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua istable (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua isstring (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua isuserdata (); 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua islightuserdata 

0 ; 

int 

Retums 1 if the objeet is eompatible, otherwise 
0 

lua lessthan (); 

int 

Compares two items on the staek 

lua pushboolean (); 

void 

Pushes Boolean value onto the staek and 
retums a pointer to the Boolean 

lua pushcfunction (); 

void 

Pushes a C funetion onto the staek and retums 
a pointer to the funetion 

lua pushfstring (); 

void 

Pushes a formatted string onto the staek and 
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Table 7.3. Lua APIStack Commands 


Command 

Type 

Purpose 

returns a pointer to the string 

lua pushlightuserdata 

0 

void 

Pushes light user data onto the stack and 
returns a pointer 

lua pushlstring (); 

void 

Makes an internal copy of given string, pushes, 
and returns a pointer to the string 

lua pushnil (); 

void 

Pushes a nil value onto the stack and returns a 
pointer to the value 

lua pushnumber (); 

void 

Pushes a numeric value onto the stack and 
returns a pointer to the number 

lua pushstring () ; 

void 

Pushes proper C strings onto the stack and 
returns a pointer to the string 

lua pushvalue (); 

void 

Pushes a copy of an element to a given index 

lua pushvfstring (); 

void 

Pushes a string onto the stack and returns a 
pointer to the string 

lua rawequal () ; 

int 

Compares values for primitive equality 

lua remove (); 

void 

Removes element at the given index 

lua replace (); 

void 

Replaces given index with given element 

lua settop (); 

void 

Sets the stack top to a given index 

lua State 

struet 

Dynamic structure that holds all Lua States 

lua totrhead(); 

int 

Converts a value on the stack into a C thread 

lua strlen (); 

int 

Gets a string's length 

lua tocfunction (); 

int 

Converts a value on the stack into a C function 

lua tonumber (); 

int 

Converts a Lua value at given index to a C type 
number. Number is a double by default 

lua tostring (); 

const 

char 

Converts a Lua value at the given index to a C 
type string (in C a const *char) 

luatouserdata (); 

void 

Translates userdata to a specific C type 

lua type () ; 

int 

Returns the type of a value in a stack 


AU global variables exist as fields in ordinary Lua tables called environment tables or 
simply environments. Functions written in C and exported to Lua all share a common 
global environment. Each function written in Lua has its own referenee to an 
environment, so that all global variables in that funetion refer to that environment table 
When a funetion is created, it inherits the environment firom the function that created it. 
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Userdata 


Userdata is used to represent C values. Lua supports two types, full userdata and light 
userdata. Full userdata represents a bloek of memory and light user data represents a 
pointer. Both are eonsidered objeets. 

The lua_type eommand wih return lua_tuserdata for full userdata or 
LUA_TLiGHTUSERDATA for light userdata when eheeking an existing userdata. New 
userdata ean be ereated with the lua_newuserdata () funetion: 

void *lua_newuserdata (lua_stat *MyLua, size_t size); 


This ahoeates a new memory bloek, pushes onto the staek a new userdata with the bloek 
address, and then returns the address. 

Tables 

The Lua API also has a few funetions for manipulating metatables in objeets. You 
ereate tables by eahing the funetion lua_newtable. This funetion ereates a new, empty 
table and then pushes it onto the staek. The funetion lua_gettableis provided for 
reading a value firom a table that resides somewhere on the staek; when lua gettabieis 
given an index that points to the table, it wih read and return the value. 

Interestingly, in the Lua API, ah global variables are kept within the ordinary Lua tables 
eahed environments. The initial environment that is ereated is eahed the global 
environment, and it ean be pseudo-indexed at lua_globals index. Regular table 
operations ean be used over an environment table to aeeess and ehange these global 
values (using lua_pushstring, for example). The global environment of a thread ean 
be ehanged using iua_repiace. 

The lua getfenv and lua_setfenvfunetions are used to get and set the environment 
of Lua funetions. First lua_getfenv pushes the environment table of the funetion on 
the staek at a given index, and then iua_setfenv pops a table from the staek and sets it 
as the new environment for the funetion at a given index. 

There are a number of other useful Lua funetions for dealing with tables. 
Lua_getmetatabie pushes the metatable of an objeet on the staek, and 
lua_setmetatable sets the table on the top of a staek as a new metatable for that 
objeet and then pops the table. The lua load eommand is used to load up Lua ehunks. 

It automatieahy deteets whether a ehunk is text or binary, and then loads it aeeordingly. 

int lua_load (lua_State *MyLua, lua_reader, void *Mydata, const char 
*MyChunk); 


The funetion lua_rawget gets the real value of a table key. To store the value into a 
table that resides somewhere in the staek, the key and the value are pushed by eahing 
lua_set table. The lua_rawest funetion is used to set the real value of any table 
index. Tables ean be traversed with int lua_next, whieh pops a key from the staek and 
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pushes a key-value pair from the table. If there are no more elements left, then 
lua_next returns a 0. 

Tables are createdby ealling lua_newtable: 
void lua_newtable (lua_State *MyLua); 


Reading the value in a table on the staek is done by ealling the lua_gettable command 
with a speeific index: 

lua_gettable (lua_State *MyLua, int specific_index); 


Because of their universality and flexibility, tables are often used as arrays in the API. 

NOTE 

TIP 

Some of you C buffs are probably wondering how Lua handles arrays. Lua does have 
functions to work with C arrays, which are treated as Lua tables and indexed by 
numbers. Lua basically tums Lua tables into arrays indexed by number keys. The API 
uses two commands to aeeomplish this: lua_rawgeti, to push the value of elements 
into the table at a given staek position, and lua_rawseti, for setting the value of 
elements of a table at a given staek position. The lua getn command is a third function 
that will get the number of elements in the table/array. 

Threads 

Lua offers partial support for multiple threads. Since the support is pretty basic, you will 
often find programs that instead incorporate an existing C library offering full multi- 
threading. 

Adding a new thread to the Lua state can be done by using the lua_newthreadfunction: 

Lua State *lua newthread (lua State *L); 


The lua_newthread function pushes the thread onto the staek and then returns a pointer 
to lua_state that represcnts this new thread. AU the global objects are then shared 
between the different threads, but this new thread has its own independent runtime 
staek. Each thread also has an independent global environment table. 

Manipulating an existing thread can be accomplished by using the lua_resume and 
lua_yield functions, which allow one to suspend or resume running threads. Lua 
threads can be closed using the lua_closethread () function. 
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Calling Functions 

When C and Lua are working in tandem, both C and Lua functions can be called. For C 
functions to work, you must do the following: 

1. Register the C function with Lua. 

2. Push the function to be called onto the stack. 

3. Push any arguments to the function onto the stack. 

4. Call the function with lua_call. 

The lua call function looks something like this: 

int lua call (lua State *MyLua, int arguments, int results); 


The arguments and results intcgcrs arc the numbers of arguments and results that 
passed onto the stack. 

If a C function needs to keep a reference to a Lua value outside of its lifespan, it must 
create a reference to the value. These references are stored and manipulated and 
released with lua_ref, lua_getref, and lua_unref. 

AU arguments and the function value are then popped firom the stack. Lua makes sure 
that the returned values fit on the stack, and that the function results are pushed in direct 
order so that the last resuit is on the top. The lua call function propagates any errors 
in this process upwards, and a special function, lua_pcall, is used to track error 
messages that flow this way. 

C functions can also be used to extend Lua, a technique that is covered in Chapter 12, 
along with extending Ruby and Python in the same way. 

Performing Actions 

Lua's C API has equivalent commands to the basic library that it uses when in C API 
mode. These commands are listed in Table 7.4. 


Table 7.4. Lua API Actions 


Basic Library Function 

dofile 0 
dostring () 
error () 
newtag () 
tag () 


Equivalent C API Function 

lua_dofile 
lua dostring 
lua error 
lua newtag 
lua_tag 
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Table 7.4. Lua API Actions 


Basic Library Function Equivalent C API Function 

type 0 lua_type 


Out of all of these, iau_dostring is the one most likely to be encountered because it is 
used to perform most Lua actions. Lua can also be executed in chunks written in a file 
or in a string by using lua_dofile, lua_dostring, or the lua_dobuffer eommand. 

When ealled with a null argument, lua_dof ile exeeutes the Standard in (stdin) 
stream. Both iua_dofile and iua_dobuffer are able to execute pre-compiled Lua 
ehunks this way. The lua_dostring eommand, however, ean only exeeute souree eode. 

The funetion lua_dostring ealls the interpreter over a seetion of eode eontained in a 
string. The lua_getglobal, lua_setglobal, lua_call, and lua_register are USed to 
interpret eode files, set and manipulate global variables, eall Lua funetions, and make C 
funetions aeeessible to Lua. 
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Summary 

Lua's capabilities should be fairly ciear at this point, and SDL has been tackled for the 
second time in this book. Here are a few important points before eontinuing to the next 
ehapter; 

• Blitting is stili the key to rendering objeets in SDL, whether using Python or 
Lua. 

• Reets are stili the key for blitting a sprite or objeet to the sereen. 

• The key to utilizing the C API is the staek. 

• Tables in Lua are used everywhere. They make good containers for game 
objeets and good eontainers for global variables in the C API. 

• The most eommonly found API funetion (after lua_state and lua_open) is 
lua dostring. 

• The Lua API funetions are held within the lua . hheader, whieh must be wrapped 
in a C extern eommand. 


307 



Questions and Answers 


1 : Q: I can't seem to get the Gravity.lua code to work. Is there anything else I 
should try? 

A: A; Make sure you have the luaSDL.dll file somewhere on your system path. 
If you are using Windows, try this; 

1. Open up a command prompt: type cmd or command from the Run 
option on the Start menu. 

2. Navigate to the Gravity directory with the command line: use the cd 
command to change directories to cd MY 
DOCUMENTS\BOOK\CHAPTER 7\GRAVITY. 

3. TypeLua.exe Gravity.lua 

2 : Q: Where can I learn more about the Eua API? 

A: A: Lua-users.org Wiki pages have a few good, short API tutorials: 
http://lua-users.org/wiki/ 

There is also an API section in the online 5.0 Lua manual: 
http://www.lua.Org/manual/5.0/ 
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Exercises 


1 : Make a copy of the Gravity.lua source code and try playing with some of the 
variables to see what happens. Change the width and height of the video 
screen, change the number of player lives, and mess with the gravity and 
speed constants. What would you add or change to make the game more 
interesting or fun? 

2: Take a look at the Meteor Shower game that comes bundled with the LuaSDL 
after you have a pretty good feel for Gravity to see what an even more 
complex Lua game looks like. Again, make some changes to the constants 
and variables. See if there is anything you would change to make the game 
more interesting or fun. 

3: Take a few of the simple Lua code samples from the last chapter try to re- 
script them using the C API. 
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Chapter 8. The Lua Game Community 


Daring ideas are like chessmen moved forward. They may be beaten, but they may start 
a winning game. 

-Goethe 

Of the three languages eovered in this book, Lua is the most widely used in the game 
industry. It is already an established tool in a handful of large game shops, and it also 
has a history with some of the biggest games to eome out on the PC. It would be folly to 
try to list all of the projects in whieh Lua has been a player (although the Lua horne site 
has a fairly large sampling of projeets). This ehapter instead highlights a few key 
projeets. 


310 



Game Engines 

Game engines are tools that help program games. In Lua's ease, some of these engines 
are open-souree and some are not; some of them are aimed towards beginners and some 
towards advaneed programmers. Some of these engines are established and eomplete, 
while others are stili in raw alpha or a quiet beta. The range of engines out there is elear 
evidenee of the language's popularity. 

Arkhart 

Arkhart is an original fantasy role-playing game that uses a unique engine called the 
Ark engine. The Ark engine and Arkhart itself are built upon Lua and SDL. Ark 
provides tools, a 3D client, and Lua seripting faeilities to those who want to try their 
hand at 3D programming Lua-style. The Arkhart horne page ean be found at 
http://arkhart.nekeme.net/en/ . 

The Arkhart eode was originally built with JavaScript and Mozilla's jslib, but it grew so 
large that the authors migrated to the current SDL platform. The Ark engine itself has a 
module for Lua scriptables, and in particular the animation files (.anm) are defined with 
the Lua module. The game AI is handled within its arkhart.lua file, which initializes 
through the Lua AI library. Areas in the game also appear to be defined by Lua files 
(quest.lua files to be exact). 

Arkhart is published under the Gnu General Public License. The Ar kh art design team is 
currently looking for developers and authors in both English and French. 

ClanLib 

ClanLib is a multi-platform game development library—perhaps one of the most 
popular libraries for amateur game designers today. The idea behind ClanLib is to take 
care of all the hard-to-develop deep functionality like sound mixing, setting up direct 
draw, and read-ing image files. ClanLib provides a way of dealing with sound, graphics, 
and networking. 

ClanLib is licensed under the GNU Library General Public License and uses Lua for 
extending itself and for seripting. It ean also be extended and scripted with Ruby, and is 
discussed in a bit more length in Chapter 11 of this book. 

Enigma 

Enigma is a "nearly complete" puzzle game inspired by Atari's Oxyd and Amiga's 
Rock'n'Roll. Enigma is free Software, with the executables and source distributed under 
the General Public Eicense; it ean be downloaded at the creatofs Website, 
http://www.nongnu.org/enigma/ . 

Version .70 is also included on the CD in the Chapter 8 file section. Currently, 
executables for both Windows and Macintosh are included with the latest release, 
although Enigma should be playable on Posix operating systems with a bit of tweaking. 
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Enigma has been developed by volunteers and has a few community sites that offer 
levels and eneouragement to new users and level designers. The game is engineered 
using Lua, SDL, and Oxydlib, whieh is a C++ library. Lua holds the distinetion of being 
the primary language for coding different levels. Enigma is an exeellent example of a 
cross C++/Lua project, and also a good example of how to tie the ability to seript levels 
into a produet; for these reasons, Tm going to spend some time foeusing on how it 
Works in this seetion. 

The Enigma world is a 2D area in whieh the player travels in the guise of a rolling black 
ball (see Ligure 8.1). The first step in creating a level in Enigma is to create a map of the 
world for the player to exist on: 

Figure 8.1. The Enigma world 



00:00 


o o 


create world(10,10) 


This creates a 10x10 block world map. Once the map has been created, each point on 
the map can be accessed like a grid. The upper-left corner is always (0,0) and, in this 
case, the map's lower-right comer is (9,9), as you are counting from 0. 

Enigma Tiles and Game Pieces 

Enigma has a number of different stone tiles (prefixed by st-), icons (prefixed by ix-), 
items (prefixed by it-), floor tiles (prefixed by fi-), and two players (ac-biackbaii 
and ac-whiteball), although player two is currently unimplemented in the engine. 
These can be used to populate the world that the player travels in. Many of the Standard 
tiles and game pieces are listed in Tables 8.1 through 8.5, although it is also possible to 
create your own. The Xs used in the object names indicate wildcards, where there are 
multiple similar tiles (for instance, there are several st-oneway_x tiles, a few examples 
being st-oneway_white-s, st-oneway_black-s, and st-oneway_white-n). 


312 



Table 8.1. Enigma Players 


Object 

ac-blackball 

ac-whiteball 


Description 

Player piece 

Second player piece (currently unimplemented) 


Object 

fl-abyss 
f1-bluegray 
f1-bluegreen 
f1-brick 
f1-bridge 
f1-dunes 
f1-gradient 
f1-gray 
f1-hay 
f1-himalaya 
f1-inverse 
f1-leaves 
f1-marble 
f1-metal 
f1-normal 
f1-plank 
f1-rough 
f1-sahara 
f1-samba 
f1-sand 
f1-space 
f1-stone 
f1-tigris 
f1-water 
f1-wood 
f1-woven 


Table 8.2. EnJgma Eloor Tiles 

Description 

Abyss floor style 

Two color combo tile 

Two color combo tile 

Orange brick style floor 

Bridge tile can be open or closed 

Sand tile 

Fading tile set 

Cray tiles 

Straw texture 

Blue snowy tile 

Inverse of fl-normal 

Green forest tile 

Golden stone 

Metallic tiles with different rivets 
Metallic tile with four corner rivets 
Wood floor, planks are cross stitched 
Granite-looking 
Desert tile 

Stone tile segmented into four pieces 
Desert tile 

Black with multi-colored stars 
Generic stone floor 
Light marble looking floor 
Water floor style 

Wood floor, four even strips per tile 
Escher-like black and white weave 
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Table 8.3. Enigma Icons 


Object 

Description 

ic-actor 

Player icon 

ic-arrow 

Mouse pointer 

ic-bottom 

Directional arrow 

ic-down 

Directional arrow 

ic-floor 

Section of 3D grid 

ic-stone 

Picture of 3D block 

ic-top 

Directional arrow 

ic-up 

Directional arrow 


Table 8.4. Enigma Items 

Object 

Description 

it-blackbomb 

Exploding bomb 

it-brush 

Paintbrush 

it-coin 

Money piece 

it-crack 

Crumbling segment 

it-document 

Scroll 

it-dynamite 

Stick of dynamite 

it-extralife 

Black ball (player pieee) 

it-floppy 

Floppy disk 

it-hammer 

Hammer 

it-hill 

Tile bubble simulates a hili 

it-hollow 

Coneave tile simulates a depression or hollow 

it-key 

Key 

it-laserX 

Different item tiles for laser items 

it-magicwand 

A magie wand 

it-magnet-off 

Magnet with no animation 

it-magnet-on 

Magnet with animation 

it-pipe 

Pipe segments 

it-seed 

Small seed bits 

it-shogund-X 

A Shogun dot, in small, medium, and large sizes 

it-spade 

Shovel 

it-springl 

Uneompressed spring 
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Table 8.4. Enigma Items 


Object 

Description 

it-spring2 

Compressed spring 

it-surprise 

Gift package with a question mark over it 

it-sword 

Sword 

it-tinyhill 

Smaller hili 

it-tinyhollow 

Smaller hollow 

it-trigger 

Metallic trigger grate 

it-umbrella 

Umbrella 

it-wormhole 

Animated spinning wormhole 

it-yanying 

Reversed yin-yang Symbol 


Table 8.5. Enigma Stone Tiles 

Object 

Description 

st-black 

Different stones with black designs 

st-block 

Standard gray stone block 

st-bluegray 

Blue and gray fading stone 

st-bolder 

Stones with different direetional arrows 

st-break 

Breaking stone animation 

st-brick 

Briek wall 

st-brownie 

Brown earthen wall 

st-coinslot 

Wall with slot for eoin 

st-death 

Stone with skull and erossbones 

st-death-munch 

Skull and erossbones animation 

st-doorX 

Different stone doors 

st-fakeoxyd=blink 

Different blinking stones / oxyd pieees 

st-floppyl 

Stone for aeeepting it-floppy items 

st-floppy2 

Stone with it-floppy inserted 

st-glass 

Stone with white glass design 

st-gratel 

Closed grate 

st-grate2 

Open grate 

st-greenbrown 

Earthen green-brown stone 

st-keyl 

Keyhole with no key 
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Table 8.5. Enigma Stone Tiles 


Object 

Description 

st-k;ey2 

Keyhole with key 

st-laser-X 

Different stone tiles for lasers 

st-magic 

Stones with a keyboard look and numbers on them 

st-marble 

Generic marble stone tile 

st-metal 

Generic metal stone tile 

st-mirror-movable 

Movable mirror tile 

st-mirror-static 

Static mirror tile 

st-mirrortempl X 

Different tiles for mirrors 

st-oneway X 

Different stones with direetional arrows 

st-oxydX 

Oxyd stone (many different game object stones) 

st-plain 

Generic plain stone wall 

st-puzzle 

Different pipe tiles 

st-rockX 

Several differently colored rock tiles 

st-rubberband 

Rubber band tile 

st-scissors 

Open scissor stone 

st-scissors-snip 

Closed scissor stone 

st-shogunX 

Several Shogun stone tiles 

st-stoneimpulse 

Impulse stone animation 

st-stoneimpulse-hollow 

Hollow impulse stone animation 

st-swap 

Broken circle 

st-switchX 

Different stoplight stones 

st-thief 

Thief stone animation 

st-timer 

Stone that triggers timed events, animated 

st-timeroff 

Triggered stone timer, no animation 

st-white 

Different white stone tiles 

st-wood 

Stone tile with wood design 

st-woven 

Escher like white weave design 

st-yellow 

Yellow stone tile 

st-yinyangl 

Yin-yang stone tile design 

Creating Enigma Levels 
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There are a number of funetions for creating levels; these are listed and described in 
Table 8.6. 


Table 8.6. EnJgma LevelDesign Funetions 


Function 

Purpose 

Arguments 

AddRubberBand 

Connects actors and stones 
that are then pulled together 
with given strength 

Actor, object, strength, length 

create world 

Sets base map 

Width and height 

def stone 

Defines st-stone 

Stone name, sound 

def floor 

Defines fi-fioor 

Floor name, friction, and mouse 
factor 

draw checker- 

board floor 

Draws floor altemating 
between two tiles 

floor 1, floor2, location (x,y), size 
(height,width), attributes 

draw border 

Adds a border to the level 

Given stone (optional; location 
in x,y,z coordinates and height + 
width) 

draw floor 

Draws given fl-floor 

Floor name, x and y coordinates 
and increments, and attributes 

draw items 

Draws given it-item 

Item name, x and y coordinates 
and increments, and attributes 

draw stones 

Draws given st-stone 

Stone name, x and y coordinates 
and increments, and attributes 

fili floor 

Filis area with partieular 

st-floor 

Floor name, attributes, x and y 
coordinates 

fili items 

Filis area with given item 

Item, coordinates (x,y,z), size 
(height) 

fili stones 

Filis area with given stone 

Stone, coordinates(x,y,z), size 
(height) 

GetAttrib 

Returns eurrent attribute 
value 

Object, attribute name 

make object 

Creates an object on the 
map, used internally by 
other funetions 

name and attributes 

set actor 

Creates a moveable object 
(actor) 

Name, x and y coordinates, 
attributes 

set attrib 

Sets an objecfs attribute 

The object, value and a key 

set attribs 

Sets several attributes at 

once 

Object, attributes 

setDefaultAttribs 

Used when placing many 

Object name, attribute 
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Table 8.6. Enigma LevelDesign Functions 


Function 

Purpose 

objects with same attributes 

Arguments 

set floor 

Sets given to f i-f loor 

Eloor name, position (x,y), 
attributes 

set item 

Sets given to it-item 

Item name, position (x,y), 
attributes 

set stone 

Sets given to st-stone 

Eloor name, position (x,y), 
attributes 

set stones 

Sets given to st-stone, but 
takes multiple position 
arguments 

Stone name, positions (x,y), 
attributes 


There are also a few Standard preset variables in Enigma, the most common being the 
following: 


level_width 
level height 
oxyyd default flavor 
EAST ~ ~ 

WEST 

SOUTH 

NORTH 

TRUE 

FALSE 


After using create world to begin an Enigma level, the next step is usually to create a 
frame of stones as a border around the map using the draw border command. To set a 
border to the st-woodtile, do this: 

draw border("st-wood") 


Thafs pretty simple. Now to fili the floor. By feeding draw_checkerboard_floor with 
the upper-left comer of the fili (as x and y coordinates), the map height and width 
(which are defined in constants already), and the two floor tiles, the floor can be filled in 
with alternating desert tiles: 

fili floor("fl-sahara","fl-sand",0,0, level width, level height) 


Now that there is a fdled map, you can use set_stone functions to create objects on the 
map. The set_stonefunction needs to know the type of stone and coordinates on the 
map and must be given a unique name (which is given as an attribute in curly braces): 

set_stone("st-grate", 4,7, {name="My_Stone"}) 
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The trick to solving a level is finding the matching onyx stones. To set these, you could 
also use set_stone: 

set_stone("st-onyx", 1,1, {name="My_oxyd"}) 


But luckily the Enigma designers made it even easier. To save a bit of typing, use the 
oxyd eommand; 

oxyd(1,1) 
oxyd(2,2) 
oxyd_shuffle() 


These commands populate four game pieees, and then oxyd_shuf f le permutes the 
eolors on the oxyd stones within the landseape. After creating the map and the game 
pieees, the fmal step is to create the player on the map using set_actor using the same 
general conventions. The player attribute should always be piayer=o for the purposes 
of the current engine code; 5, sare the starting x,y coordinates, and ac-blackball is the 
player piece: 

set_actor("ac-blackball", 5,5, {player=0}) 


The Enigma source code (also included in the Enigma file folder on the CD) comes with 
a documents folder that includes more detailed instructions for level design, as well as 
many level examples (over 100) for the budding builder. The source itself is a great 
example of using Lua in combination with SDL. 

Gime 

Gime is a two-dimensional game development platform primarily used for fast 
prototyping. Gime uses SDL as the graphics System, and has an API that is scriptable 
with Lua. Gime also comes with a GUI system for creating Windows and dialog boxes. 
Gime is written in C and is basically a glue language layer between SDL and Lua. It is 
currently only in prerelease (alpha) and is available at its homepage under the GNU 
Public License, http://www.gime.org/ . 

The Gime API actually has two important Lua parts: a LuaGUI library and a LuaUtil 
library. The LuaGUI library is capable of handling different typefaces and images. Its 
typface eommand supports both BDL and TL fonts, as well as different styles and sizes 
of text. Image processing is done with a wrapper to several SDL functions and allows 
Gime, through an image eommand, to create colored surfaces for text with Standard 
opaque and alpha and colorkey settings. The GUI also supports drawing routines for 
filling and updating surfaces, events processing for returning information on keyboard 
presses and mouse movements, and a few miscellaneous functions for tracking firames, 
timing, and debugging. 
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The LuaUtil library is used for file manipulation, string manipulation, bitwise 
operations, and creating cache tables, whieh Gime uses to store value types (tables) and 
weak referenees. Gime currently requires Lua 4.0, SDL 1.2 or higher, SDL_image, 
SDL_ttf, freetype 2.0, and SDL_mixerfor musie. 

HZ Engine 

The HZ Engine is a development projeci by David Jeske, who wanted to re-create 
Herzog Zwei, a classic Sega Genesis game released in 1990 by Technosoft. Herzog 
Zwei was one of the first real-time strategy games and a precursor to popular tities like 
Command and Conquer, Total Annihilation, and Age of Empires. 

Since its creation, HZ has grown into a rough platform and a nearly full real-time 
strategy game engine. The original version was built for Windows, but David Jeske has 
ported the latest to run on Einux/Xwindows. Eeatures include 

• A sprite and tile engine 

• 2D hardware blit support on Win32 (whieh makes it a very fast engine) 

• 8-or 16-bit color 

• Third-person RTS-style view 

• Eua scripting 

HZ uses an older version of Eua (3.1) and C as its primary driver. Since many of the 
game's features are based on the embedded Eua, you can interactively query for 
information about the game using the Eua console. The backtick (') key will bring up a 
Eua console while the game is being played, and you can actually script and write new 
code from the text console. In its current implementation, you can, by using the 
backtick, toggle between the game screen and the prompt that accepts Eua. 

Besides being able to script events live and experiment with the Eua console while 
playing the game, you can completely define sprite objects using Eua. This includes 
everything from UI to behavior to physics. 

Browsing through the source of the game (whieh is also available on the project 
Website), you can see that the engine initiates an init.lua file during the game startup. 
The lua.init file loads up the other necessary Eua files (using the dof ile command from 
Eua's basic function library—refer to Chapter 5 for more). 

Sprite initiation is one of the things Eua Controls in the HZ Engine. Visually, the sprites 
are defined within the visrep.lua file, where you can find the code that creates the 
sample bases and tanks in HX. David Jenke also includes a sample sprites.lua file with 
examples of how to create the visual representation. A sprite that only uses one image 
would look like this: 

SimpleSprite = {"image.bmp"} 


A more complicated image with several images to indicate an animation or different 
traveling directions would include those images and an index: 
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ComplexSprite = { 


{ 

{ 

{ 

{ 

IndexedBy 

} 


"imagel.bmp" 
"image2.bmp" 
"imageS.bmp" 
"image4.bmp" 
= "CSprite" 


}, 

}, 

I 

}; 


The IndexedBy Une tells the HZ Engine what object variable holds the array (table) of 
images. The game engine reads these values to determine which to draw (the default is 
the first image). You ean ehoose one of the other images by setting the image_frame in 
the eode. 

The sprite logie, as well as the sprite images, are defined with Lua. The engine runs in 
frames, and in each frame sprites are redrawn, key presses are listened for, and sprite 
eollisions are deteeted. 

NOTE 

CAUTION 

In the existing eode files, these image deelarations are followed by a number of zeroes. 
The zeroes were for functionality that was never implemented, and they are no longer 
relevant or neeessary, but they may eause eonfusion beeause of the obvious differenee 
between the existing eode base and the eode samples. 

Eaeh sprite also has a doTick () method that is ealled at eaeh iteration of the engine. 

The doTick method ean be used to decide which image to show and set the object 
properties for. These properties ean be anything you ean dream up in Lua, but Jenke has 
reserved some functions in C so that the engine runs at an optimal speed. These 
functions are highlighted in Table 8.7. 


Table 8.7. HZ Engine 's C Functions for Lua Sprites 


Function 

C_obj_delete(objnum); 

C obj viewFollow(objnum); 
C_obj_getVelocity(objnum); 

C_obj_setVelocity(objnum,vx,vy); 
C_obj_getPos(objnum); 

C_obj_setPos(objnum,x,y); 

C_obj_setLayer(objnum,layer_number); 


Purpose 

Removes a sprite 

Main camera will follow this sprite 
Gets the velocity of a sprite 
Sets the velocity of a sprite 
Gets the position (x,y) of a sprite 
Sets the position (x,y) of a sprite 
Sets the graphic layer of a sprite 


These functions take in objnum as their first parameter and x,y coordinates to follow. 
Eor instance, here's how to get an object position: 
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Co_obj_getPos(self.objnum); 

and here's how to set the position; 

Co_obj_setPos(self.objnum, 100, 80); 


Having the C++ engine do the range checking and math greatly speeds up the HZ 
Engine. C++ is also used to handle collisions. Each sprite in HZ has a ge_collision () 
method. The point of a collision given by x and y parameters and the object that is hit 
are provided by a whoihlt parameter, which is a Lua script object. 

The keyDown and keyUp event methods detect which keys are being held down. Key 
methods vary between platforms, making it difficult to design cross-platform, but they 
should suffice for game events. The inputEvent is used for taking in a name or typing 
strings from a player. More HZ documentation, the binaries, and source code can be 
found at David JerLke's Website and HZ project page, at 
http ://pulp .fiction.net/~j eske/Proj ects/HZ. 

Lixoo 

Lixoo is a small, 2D, mouse-driven adventure game engine designed for conversation 
and character-based computer games. Lixoo consists of both the driving graphics engine 
and also a number of tools for users to build their games with. The main use of Lua in 
Lixoo is as an IDE with modules for creating rooms, characters, music, and animation. 

Currently, Lixoo is under development and works only on OS X and Linux. It was 
originally written with ZeroLorce (a small C library) but has since moved to C++. 
Lixoo's project page can be found on Sourceforge at http://lixoo.sourceforge.net/cgi- 
bin/cgilua/content.html?section=liles . 

The Lune Mud Server 

Lune Mud is a text-based, multiuser dungeon that uses a modified Lua interpreter. Lua 
provides the functionality for sockets, time, and directory listings. Lune Mud runs on 
Linux and Win32 platforms and was written by Jason Clow. 

Lune Mud is in early development but is playable. It is licensed under the GPL and can 
be found at Sourceforge, at http ://lune. sourceforge .net . 

The MADProject 

An adventure-game project based on the classic Sierra Quest games, MADProject is an 
opensource, cross-platform, script-driven game engine, and, yes, Lua is the script that 
drives it. In its current iteration (as of this writing) MAD runs only on DOS and 
Windows, but the community is working on porting to Macintosh and Posix systems as 
well. 
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The MADProject was founded by Rick Springer. More recent development has been 
undertaken by projeet leader Nunzio Hayslip and lead programmer Javier Gonzalez, and 
Posix porting is being taekled by Christopher Reichenbach. MAD features inelude the 
following: 

• Sprite animation 

• Pathfinding 

• An in-house GUI 

• Musie and sound effects (MIDI, WAV, and MP3) 

• A Lua-based seripting interfaee 

Windows maehines must have a DLL file (allegdl.dll) plaeed on their path or within 
their Systems folders in order to run the MAD sources and binaries. The engine eomes 
with an example game ealled Lambazzo, whose code is the basis for the code in this 
section. 

MAD leverages a number of other community resourees besides Lua, in partieular the 
allegro, alfont, almp3, and zlib libraries. It comes equipped with an interpreter and 
several Utilities, all within the tools directory of the MAD source tree. Besides Lua, 
MAD also uses its own proprietary file format (*.mad), MAD animation files (*.anm), 
image files (*.img), and graphical scen files (*.scn). 

The official homepage for MAD is http://mad-proiect.sourceforge.net . There is also a 
Sourceforge projeet page, at http://sourceforge.net/proiects/mad-proiect/ . 

MAD accepts and uses full-force Lua. Lua is used to set variables and tables, perform 
loops, operate math, and set control structures. The latest version of MAD (of this 
writing) is 1.9 and is included in the Chapter 8 section on the CD. 

MAD relies on a number of specific files. It searches the computefs primary archive for 
stdmad.lua and main.lua, the first two Scripts it needs to run. Another important file is 
mad.cfg, which is used to determine the primary file archive and what screen size to set 
the display to. The mad.cfg file has the Standard format of a Windows .ini file. You can 
also prompt mad.cfg to run in safevideo mode. Another important file is stdmad.lua, 
which can be hacked to alter or add custom actions and cursors to MAD. 

MAD Tools 

MAD files (*.mad) can be created with the MAD File Archive Manager (Mfile). Mfile 
can compile many game resourees into a single compressed data file. Mfile is used to 
build MAD archives and compress the files MAD will use. The command line is used to 
run Mfile, and Table 8.8 lists a few of Mfile's runtime flags. 


Table 8.8. Mille Commands and Switches 
Switch Use Example 

< Use a script to build a MAD fde mfile -n MyFile.mad < MyScript.in 

Create anew archive mfile MyFile.mad 
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Table 8.8. Mfile Commands and Switches 


Switch Use Example 

None Open an archive mfile MyFile.mad 


The MAD Scene Generator (Scengen) takes as input a background image, a mask 
image, and a wase image, and puts them all together to create a scene. Scengen.exe 
combines these three images (normally bitmap layers) into one format, a .scn format, 
that the MAD engine can read and use. This is done via command all on one line, 
naming the scene (MyScene) and then feeding the three bitmaps: 

secnegen.exe MyScene.scn background.bmp mask.bmp wasc.bmp 


After you create scenes you can view them with the MAD Scene Viewer, Sceneview. 
Sceneview can also be loaded with alternate resolutions by designating them on the 
command line. For instance, to load a scene at 640x480, do this: 

scenview.exe MyScene.scn 640 480 


The FIO key can be used to write bitmaps in scenview.exe into the current directory. 

MAD's Animation Generator (anmgen) creates the animation file types (.anm) MAD 
uses. To create an animation file, you need to give anmgen the animation-creation script 
file (.asr) and the generated animation file (.anm) on the command line: 


anmgen.exe MyScript.asr MyAnimation.anm 


Animation script files have two sections separated by three percentage symbols: %%%. 
The first section lists all of the frames filenames to be used in the sub-animations: 

walkingl.bmp 
walking2.bmp 

walkingS.bmp 

0 , 0 , 0 , 
o o o 


The second section lists all of the frame filenames that are used in the sub-animations. 
First, the sub-animation is named, then, in parentheses, the time to display each of the 
frames is given: 


walking(10) 


A comma can be used to designate flip fiags, with a 0 indicating no fiipping, a 1 
designating a vertical flip, a 2 designating a horizontal flip, and a 3 designating a 
vertical and a horizontal flip: 
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/* no flipping*/ 
walking(10, 0) 

/*Vertical Flipping*/ 
walking(10, 1) 

/*Horizontal Flipping*/ 
walking(10, 2) 

/*Both Horizontal and Vertical Flipping*/ 
walking(10, 3) 


After the flip frame is designated, the frame numbers are listed, separated by a space: 

walking(10) 0 1 2 


There is also an anmview.exe utility for viewing animation files. It loads up the 
animation in a viewer; then the spaeebar ean be pressed to play the eurrent sub- 
animation. The arrow keys ean be used to change the currently displayed frame. 

Imgconv is an image converter that eonverts .bmps to MAD's image format, .img. It ean 
eonvert a BMP file to a MAD image file or viee versa. 

NOTE 

MAD runs in 320x420 video mode with high resolution (16, 24, or 32bpp) by default. 

Some video eards no longer support the elassie 320x240 in 16/24/32 bit modes, and you 
may reeeive errors (something like "You need a direct x eompatible video eard") when 
trying to run MAD games. There is a safevideo eommand switeh, mad.exe - 
safevideo, that you ean run to get around this issue. 

MAD API 

MAD has an API that performs various System and engine tasks and sends Information 
to the kernel. The funetions are listed in Table 8.9. 

MAD Scenes 

Seenes are the baekground of a MAD game. Eaeh seene is eomposed of three bitmaps: a 
24-bit baekground, an 8-bit mask, and an 8-bit walk/scale. See Eigure 8.2 for a sample 
MAD game seene. 


Figure 8.2. A sample seene from MAD 
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Table 8.9. MAD API Functions 


Function 

Purpose 

GetKey() 

Returns code of the last key pressed 

GetKeyState () 

Returns state of key eonstant passed to it 

GetKeyWait() 

Returns eode of the last key pressed, waits if nothing has been 
pressed 

GetMouseBtn() 

Returns 1 if given mouse button is pressed down, 0 if if s not 
pressed down 

GetMouseX() 

Gets X position of the mouse pointer in pixels firom top left 
eomer of the sereen 

GetMouseY() 

Gets Y position of the mouse pointer in pixels firom top left 
eomer of the sereen 

GetTickCount() 

Returns time in milliseeonds sinee MAD has started 

LoadGlobals () 

Used to load global variables or tables firom a speeified file 

RunScript () 

Used to have interpreter mn through and add any funetions or 
variables from a given seript into the global environment 

SaveGlobals() 

Saves global variables or tables to a speeified file 

SetGUIArchive() 

Sets the filename for an archive to store game files 

SetMadSpeed() 

Speeifies the update speed in milliseeonds; speed value of 1 is 
maximum speed 

SetMasterVolume() 

Used to set digital, MIDI, or MP3 volume from 0 (quiet) to 255 
(loud) 

SetObj ectArchive() 

Sets the filename for an arehive to store game files 
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Table 8.9. MAD API Functions 


Function Purpose 

SetSceneArchive () Sets the filename for an archive to store game files 

SetScreenFX () Specifies an FX filter to apply to a screen after the sprites are 

drawn 

SetSoundArchive () gets the filename for an archive to store game files 


Create a scene with the following steps: 

1. Assign a name (and initial memory) to the new scene. 

2. Assign a particular script for the scene to run. 

3. Load the actual scene file into RAM. 

4. Start the scene running. 

Step 1 is accomplished using the NewScene command; 

My Scene = NewScene() 

The SetScript command is used to accomplish Step 2: 

My_Scene:SetScript("My_Script.lua") 


Loading the scene file into RAM, Step 3, is done with the Load command: 

My Scene:Load("My Scene File.scn") 

And then, finally, you run the scene. In this example, running the scene causes 
My_Scene_File. scn to bc drawn and My_Script. lua to start cxccuting: 

My Scene:Run() 


A game will likely be composed of a number of different scenes; use the Run () function 
to jump from one scene to another. 

There are a couple of other scene functions for dealing with loading and unloading 
scenes from memory. These include 

• SetFileName . Scts a sccnes filename without loading it into memory. 

• Unload . Frces a scene's bitmaps from memory. 
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• isLoaded () . Checks whether or not the bitmaps for a function have been loaded 
into RAM. 

As I mentioned, every MAD scene is composed of three bitmaps. The first is the 
baekground bitmap. The baekground bitmap is the aetual imagery used for the 
baekground, the illustration that sets the seene; it must be 24-bit. 

The Mask seene is the seeond bitmap, an 8-bit bitmap that is used to designate objects 
the player ean walk behind on a baekground seene. Build a seene by drawing solid gray 
masks of the objeets and then drawing a reetangle around the objeets. If the reetangles 
of two different masks interseet, then a different shade of gray must be used so that 
MAD ean make a designation between the two objects. These reetangles ean be created 
in scenegen.exe by right-clicking. The scenegen.exe right-click menu also grants access 
to a few drawing tools, including Peneii, Paintbucket, and Undo, with a right-click. The 
reetangle command actually writes the text you'll need for the mask to a file. When 
drawing these reetangles, be sure to start at the top-left and move to the bottom-right; 
otherwise, the script will give out negative numbers. 

There is some scripting involved with the mask, as well. Each objecf s reetangle must be 
defined with a NewMaskObj () command, so that the engine understands the size of the 
objects and whether other objects are drawn in firont of or behind them. 

The WaSc layer is the third and final bitmap layer that makes up a scene file. WaSc is 
short for Walk Scale, and this bitmap designates which areas of the screen the player 
ean walk in. Areas of this mask that are painted with an index of 0 are designated as not 
walkable by the player. 

The WaSc is also an 8-bit bitmap. In addition to designating unwalkable areas, it ean 
also set the scale of objects drawn at given points in the scene. Depending on the 
baekground drawing, you ean set the distance scale of the sprites; this is also 
accomplished with the index value. An index of 50 draws the objects at 50 percent, or 
half their original size, while an index of 100 draws the sprites at their original size. 

The point in a scene that determines where a sprite is to be drawn is always the middle 
bottom of the sprite. This is because this is where the feet of most characters in MAD 
would be in a drawn sprite. 

MAD Objects 

Anything that a player ean interact with in MAD is considered an object of some sort. 
The primary indicators of an object are that they move and that they are independent of 
their baekground. The steps for creating an object in MAD are as follows: 

1. Allocate memory for a new object. 

2. Load any animations the object will use. 

3. Set the object into a scene. 

4. Set any object attributes, fiags, or graphic fdters. 
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5. Show the object. 


Step 1 is accomplished with the NewOb j command; 

My_Object = NewObjO 


This step has to done first before any other eommands ean be run on an objeet. Objeets 
on the move are likely to use animations of some sort, so there is a LoadAnimation 
eommand that will load MAD animation files (*.anm) and set the animation faeing and 
looping; 


My Object:LoadAnimation("MyAnimation.anm","My faeing", 0) 


This loads up the MAD animation, sets the animation faeing to My_facing (whieh is an 
attribute set within the animation), and sets the looping to 0. The SetScene funetion 
plaees the objeet within a seene at a eertain position using (x,y) eoordinates: 

My_Object:SetScene(My_Scene, 10, 200) 


There are a handful of attributes that may or may not be neeessary for a given objeet; 
Setsize speeifies the height and width of an objeet and SetSpeed speeifies the 
horizontal and vertieal speed of an objeet. Objeet fiags are also eommonly used by the 
engine. These fiags are listed in Table 8.10. 


Table 8.10. MAD Object Fiags 

Flag Purpose 

OBJFLAG_8WAYANiM Tells MAD that the objeet eontains eight sub-animations 

for direetional movement 

OB JFLAG_ISCHARACTER Sets objeot as a "eharaeter" 

OBJFLAG_iSEGO Sets objeot as a player-eontrolled eharaeter 

OBjFLAG_iSEGOAND8WAYANiM gets objeet as both eontrolled eharaeter and eontaining 

eight sub-animations 

0 BJFLAG_N 0 SCALE Tells MAD to not reseale grap to fit the seene's wasc 

OBjFLAG_DRAWASBKG Draws objeet as part of the baekground pass, before 

other objeets 

OBJFLAG_DRAWASFRG Draws objeet as part of the foreground, after other 

objeets are drawn 


Graphie filters are set with the SetGFXFilter eommand and generally use a flag and a 
eoior (red, green, blue, or alpha) as input to ereate an effeet when drawing an objeot on 
the soreen. The following fiags are defined within the stdmad.lua file: 
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GFXFILTER_TINT. Tints the color of an object 


GFXFILTER_BLEND. Blends the object with its background 

These flags work as expected. For example, let's say you want to have a few flags and 
manually set the speed and size of an object: 

My_Obj ect:SetSize(10,10) 

My_Obj ect:SetSpeed(1,1) 

My_Object:SetFlags(OBJFLAG_ISCHARACTER + OBJFLAG_8WAYANIM) 

My_Object:SetGFXFilter(GFXFILTER_BLEND) 


The last step in creating a MAD object is to actually show it. AU objects by default in 
MAD start out invisible. You use Show to make them appear and nide to make them 
disappear: 

MyObj ect:Show() 

My_Obj ect:Hide() 


You can run a kill command to destroy or remove an object. Doing so will de-allocate 
memory applied to an object: 

My_Obj ect:Kill() 


A number of MAD graphic functions just for objects exist; they are listed in Table 8.11. 


Functions 

GetAnimFrame() 
GetAnimState 
LoadAnimation() 
Loadimage() 
PauseAnim() 

ResumeAnim() 
SwitchAnim() 


Table 8.11. Object Graphics 
Purpose 

Returns current position of the sub-animation 

Returns 0 if animation is stopped, and a 1 if animation is running 

Loads a MAD animation into the object 

Loads a MAD image into the object 

Pauses the current animation 

Resumes the current animation (after pausing) 

Changes current sub-animation and loop parameter 


Path-Flndlng 

You can set an objecfs position on the scene and move an object around by using the 
SetPosition command and giving MAD the (x,y) coordinates: 

MyObj ect:SetPosition(1,5) 
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It isn't actually necessary to use SetPosition when first creating an object because 
SetScene will place the object into the scene. When an object needs to move, and move 
in an animated way, it is usually best to use MAD's built-in path-finding. Mad actually 
has a number of functions for creating mobile objects within its scene; these are listed in 
Table 8.12. 


Function 

GetDistance 

GetMaskDistance 

GetPosition 


Table 8.12. MAD Path-Finding Functions 
Purpose 

Calculates distance between two objects in pixels 
Calculates distance between an object and a mask object 
Returns current (x,y) coordinates 


GetPositionChange Retums thc changc in position of the object since the last frame 

Returns speed of the object per frame 

Sets object position to given coordinates 

As above, except uses top-left positioning 

Returns horizontal and vertical speed of the object per frame 

Object will walk to given coordinates. Object will move around 
any not walkable areas of the scene 


GetSpeed 

SetPosition 

SetPositionTL 

SetSpeed 

WalkTo 


By default, each function (except where noted) uses x and y as the coordinates within 
the scene. By default, MAD places an object by its middle-bottom position, the idea 
being that it is easier to drop a character onto a flat (2D) floor if you're using a middle- 
bottom position. The functions that use top-left (TL) positioning are the exceptions to 
this MAD rule. 

Interacting with Objects 

Certain object actions can be bound to script functions. This is done using a 
BindAction command and a number of object action flags. These flags correspond to 
cursors within the MAD GUI and are listed in Table 8.13. 


Flag 

OBJACTION_ARROW 
OBJACTION_BUSY 
OBJACTION CURITEM 


Table 8.13. Object Action Flags 

Cursor Purpose 

ARROW Calis function when arrow cursor is used 

BUSY Calis function when busy cursor is used 

CURITEM Calis function when the currently selected 
inventory item cursor is used 
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Table 8.13. Object Aetion Flags 


Flag 

Cursor 

Purpose 

OBJACTION CUSTOM 

CUSTOM 

MAD has space for custom, programmer 
defined cursors 

OBJACTION DROP 

DROP 

Calis function when drop cursor is used 

OBJACTION HELP 

HELP 

Calis function when help cursor is used 

OBJACTION EGOWALKOVER 

N/A 

Calis function when EGO object walks over 

OBJACTION LOOK 

LOOK 

Calis function when the look cursor is used 

OBJACTION TALK 

TALK 

Calis function when the talk cursor is used 

OBJACTION TARGET 

TARGET 

Calis function when target cursor is used 

OBJACTION UPDATE 

N/A 

Calis function with every frame update 

OBJACTION USE 

USE 

Calis function when the use cursor is used 

OBJACTION WALK 

WALK 

Calis function when walk cursor is used 


Masks 

While MAD uses Standard objects to handle sprites and characters that actually move 
around the screen, it uses Mask objeets for immovable baekground pieees and 
deeorations. Mask objects are considered the second type of object in MAD, but Masks 
are stationary, and their graphies are taken from the scene files and mask layer. 
However, the code for manipulating Mask objects is nearly identical to the code for 
manipulating objects themselves. 

Mask objects are set up just like Standard objects, but since they are based on a mask and 
the baekground layer of a scene file, not all object functions are available to them. The 
functions that are available, and the functions that are unique to masks, are listed in 
Table8.14. 


Table 8.14. Mask Object Functions 


Function 

BindAction() 
GetPosition 
Kill 0 
Hide() 

NewMaskObj() 

SetFlags() 
Show() 


Purpose 

As object function 
As object function 
As object function 
As object function 

Creates a new Mask object with given scene, (x,y) coordinates, width 
height, and color index 

Sets Mask flags 

As object function 
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There is also a single Maskflag, maskobjflag_nodraw, that will set masks to appear as 
part of the baekground but not be drawn. 

Ego 

The main player in MAD, otherwise known as Ego, has a number of functions with 
whieh to handle information and its display, but is otherwise just another MAD object. 
Ego is set with the flag objflag_ischaracter, and must have a number of additional 
animations loaded with the following sub-animations: 


eaststill 

eastwalk 

northstill 

northwalk 

southstill 

southwalk 

weststill 

westwalk 


If the eharaeter is also set with objflag_8wayanim, it eontains the following additional 
walking animations: 


nestill 

newalk 

nwstill 

nwwalk 

sestill 

sewalk 

swstill 

swwalk 


The MAD GUI 

MAD eomes with a built-in eustomizable GUI system that allows designers to 

• Alter the mouse cursors 

• Set fonts 

• Create buttons and bars 

• Create pop-up Windows and boxes 

• Customize the GUI firame or skin 

These eommands are outlined in Table 8.15. There are a few UI boxes that are hard- 
eoded into the engine. These inelude the basie menu, the ehoiee box, and bello world 
message box. 

Aeeeptable fonts for MAD inelude the following: 

CEE 
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CID-keyed Type 1 fonts 
OpenType (TrueType and CFF) 
SFNT-based bitmap fonts 
TrueType 
Type 1 

Windows FNT 
XI1 PCF 


Table 8.15. MAD GUI Functions 


Function 

AddFloatingInput() 
AddFloatingText() 

Button BindActionO 
Button_Hide() 

Button LoadAnimO 

Button LoadBmpO 

Button_SetFlags() 
Button_SetText() 

Button_Show() 

ChoiceBox() 

GetCursor() 
LoadCursor() 

MenuBox() 

MoveFloating- 


Purpose 

Creates a floating input 
box 

Creates and retums 
floating text objeet 

Binds a given funetion to 
the button 

Hides a button bar and all 
of its buttons 

Loads an animation into 
the speeified button 

Loads image file into 
speeified button 

Sets the button fiags 

Speeifies the label of a 
button 

Shows a button bar and all 
its buttons 

Displays question on 
sereen with two choiees 

Returns cursor_state 

Speeifies the mouse 
eursor animation 

Displays question on 
sereen with several 
ehoiees 

Moves given floating 


Notes 


Must be MAD image format 


Hardeoded, ean be positioned, 
stops game 


Hardeoded, ean be positioned, 
stops game 
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Table 8.15. MAD GUI Functions 


Function 

Purpose 

Notes 

InputBox () 

input box to given (x,y) 
eoordinates 


MoveFloatingText () 

Moves floating text objeet 
to given (x,y) eoordinates 


MsgBox () 

Window that displays 
messages on sereen 

Hardcoded, can be positioned, 
stops game 

NewButton() 

Creates a button inside of 
a button bar 


NewButtonBar () 

Creates a bar that holds 
GUI buttons 


RemoveFloating- 
ImnputBox() 

Removes given floating 
input box 


RemoveFloatingText() 

Removes given floating 
text objeet 


SetCursor() 

Sets seleeted cursor state 

States are listed in Table 8.16 

SetCursorCycling() 

Enables or disables right- 
clicking through cursors 


SetCursorFocus () 

Sets the cursor graphio 
focus point 

Focus point is the (x,y) point in 
the mouse graphio that the 
sereen considers "clicked" 

SetObj ectUpdate- 
InGuiBoxd() 

Turns GUI background 
animations on or off 


SetSystemFont() 

Loads a font file to be 
used as game text 

Acceptable font formats follow 

SetTextButton- 
Outlines() 

Turns text button outlines 
on and off 



Here are steps for ereating a GUI button bar: 

1. Create the button bar using MyButtonBar = NewButtonBar (lO, 1, width, 
height) . You must include x and y eoordinates, width, and height. 

2. Set any optional options, ineluding a bar images and rgb values. 

3. Add buttons to the button bar using MyButtonBar :NewButton (width, height, 
ox, oy) . The width, height, and x, y offset are required. 

4. Add any optional button arguments, such as a bound function. 
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5. Specify the button label with MyButtonBar : Button SetText (MyButton, 
:"label") . 

6. Show the button bar on the sereen with 

MyButtonBar:Button_Show(MyButton) . 


The MAD mouse pointer within the GUI has a number of States that ean be set. This 
allows the player to perform a number of different actions. There are a few built-in 
mouse pointer States, as well as room for a number of eustom States, eaeh of whieh 
returns a different number. These possible cursor States are outlined in Table 8.16. 


State 

CURSOR_ARROW 

CURSOR_BUSY 

CURSOR_LOOK 

CURSOR_WALK 

CURSOR_TALK 

CURSOR_USE 

CURSOR_CURITEM 

CURSOR_TARGET 

CURSOR_DROP 

CURSOR_HELP 

CURSOR CUSTOMl 


Table 8.16. Possible Cursor States 

Number Returned 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 through 42 


The keyboard is managed in a similar way to the MAD engine, with eaeh state returning 
a specific number. These numbers start with KEY_A = l, key b = 2, and so on. The 
Standard GUI skin ean also be used to create eustom GUI boxes, whieh ean possess 
animations and eustom graphics. These graphics are also referenced by number—top 
window border = 1, bottom window border = 2, and so on. For a complete listing of 
these GUI features, check out the documentation that comes with MAD and is also 
included on this book's CD. 

MAD Sounds 

MAD ean load and play .wav, .voc, .mid, and .mp3 files for sound effects and music. To 
play sounds or effects in MAD, follow these steps: 

1. Initialize the sound object. 

2. Load the sound file. 
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3. Play the sound file. 

4. Delete the sound file when it's done. 

Step 1 is aceomplished with a simple deelaration, NewSound (), which loads a new 
sound structure into memory: 

My Sound = NewSound() 


After the sound is in memory, you can use LoadWave or LoadMpS to load a particular 
sound file; 

My Sound:LoadWav("My Wav File.wav") 


Then play the sound using Play: 

My_Sound:Play(0) 

Playtakes input on how many times to loop the sound, in this case a big 0. 

Finally, delete the sound using DeleteSound (): 

DeleteSound(My_Sound) 


Playing a music loop is an almost identical process. The NewMusic command is used 
instead of the NewSound command, and .mid files replace .wav files, although MP3s can 
also be used with NewMusic: 

My Sound = NewMusic() 

My Sound:LoadMidi("My Wav File.mid") 

My_Sound:Play(0) 

DeleteSound(My_Sound) 


Items and Spells 

The MAD engine handles spells that the player casts and the items that he uses in a 
nearly identical way. Each is associated with an ID number, and the actions performed 
by spells or items are left for the programmer to script. The spells and inventory items 
are handled the same way. The showinventory and showSpells commands take in the 
following parameters: 

• X and y coordinates (x, y) 

• Back window texture (MyTexture . img) 

• Total size of the window (window width, window height) 

• X and y coordinates for the item box, where ali inventory items are drawn in 

(itembox width, itembox height) 
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• Any item box offset (itembox ox, itembox oy) 

• Icon size (itemicon_width, itemicon height) 


The Inventory window in game can be toggled on and off using the Hideinventory 
command. Items within the Inventory box can be either bitmaps or animations. 
Inventory items are added to the window using AdditemToinv. AdditemToinv also 
takes in a number of parameters: 

• Myitem.img, which is the bitmap filename to use. 

• Myitem.anm, which is the animation filename to use. 

• Item Name is the name of the item. 

• Weight is how much the unit weighs in game units. 

• Quantity is how many units of the item stack up in the slot. 

• Description Message is the message that appears when the item is examined. 

Finally, there are a number of functions available for MAD items and spells. These are 
outlined in Table 8.17. 


Function 

f use item 
f_combine item 
RemoveltemFromInventory( 
SetCurInvItem() 

GetCurInvitem 
GetCurInvItemlD() 
AddSpellToBook() 
RemoveFrom SpellBookO 
GetCurSpell () 
GetCurSpelllD 


Table 8.17. MAD Item and Spell Functions 
Purpose 

Global function to call when the item is used 
Name of function to call when the item gets used 
Removes items 

Specifies the currently selected item 
Retrieves currently selected item 
Retrieves the currently selected item IDs 
Adds spell to spellbook 
Removes a spell from the spellbook 
Retums currently used spell 
Retums current spell ID 


This makes MAD very customizable; spells and inventory items can launch any of the 
code already mentioned, as well as operate familiar Lua constructs. 


338 




Graphics 


Lua is no slouch when it comes to graphic application integration. Lua owns a handful 
of open engines and even one that has been used in several commercial games. 
Although it is uncommon to find a completely Lua-based graphic engine, it's extremely 
common to find engines that rely on Lua to perform the underlying scripting. 

Apocalyx 3D Engine 

Apocalyx is an OpenGL 3D engine that includes Lua scripting support. The engine 
comes with a built-in console that can be launched and will fire Lua Scripts or execute 
lines of Lua. The following commands are viable on the command-line console: 

h. Reads the complete list of commands. 

1. Reads a list of the Scripts. 

r. Executes a script. 
c. Compiles a script. 

i. For entering Lua lines. 

Apocalyx has an entire API with exposed features and classes for Lua to manipulate. 
These classes are highlighted in Table 8.18, but for complete reference, check out the 
Online manuals at the Sourceforge project page, at http://apocalvx.sf net . 


Table 8.18. The Apocalyx API 


Class 

Purpose 

Child classes 

Background 

Used to render the sky and out of reach 
background objects 

HalfSky 

Image 

Converts images and checks for alpha 

Texture 

Material 

Holds the light properties of a surface 

BumpedMaterial 

Reference 

Changes position and orientation of 
objects in 3D space 

Transform (parent class). 
Camera, Object 

Sample 

Creates sounds 

SampleSD, Sound, Music 

Simulator 

Holds physics data 

ParticleSet 

Socket 

Holds methods for networking 

Host 

Terrain 

Renders the ground 

Scenery 

Win 

Manages application window 

Scene,World, Filesystem 

Zip 

Holds methods that retrieve data firom 
zip fides 
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Doris 


Doris is an OpenGL viewer driven by Lua. It uses Lua, bound to OpenGL, GLUI, and 
GLUT, for creating graphics Scripts. Doris was mainly built to perform graphical 
experiments, but it is also great sample code for leaming how to code with Lua, 
OpenGL, and 3D. 

Doris can be found on the Doris Sourceforge page, at http://doris.sourceforge.net . Doris 
was created by Nick Trout and named after his pet hamster. Currently there are versions 
of Doris for both Lua 4 and Lua 5. The Sourceforge page includes Lua code samples. 

Nebula 

Nebula is an open-source, 3D, real-time game engine written in C++. Nebula is actually 
scriptable through a number of languages, including both Python and Lua. It supports 
Direct X (8.0 and 8.1) and OpenGL and currently runs on Linux and Windows worlds. 

Nebula is a base technology engine released by Radon Labs in Berlin, at 
http://www.radonlabs.de . Radon is responsible for a few large game products, including 
Project Nomads, released by CDV in 2002, and Urban Assault, released by Microsoft in 
1998. 

Radon is currently at work on the second generation of Nebula, Nebula2, available as a 
Sourceforge project. This new version of Nebula will include a new graphic System and 
subsystems and improvements to the code used for programming on the X-Box and will 
also incorporate changes made to the Nebula engine firom the recent publishing of a few 
Radon games. Radon also pians to port Nebula to OpenGL and Linux and do a rewrite 
of Lua and Python support for the new engine. For more information on Nebula, check 
out the Nebula Wiki, at http ://nebuladevice. sourceforge.net/cgi-bin/twiki/view/Nebula/ . 
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The Games Themselves 


Lua has been a part of the game industry for many years, and it probably comes as no 
surprise that if s been used in dozens of commercial tities. Lua can take pride in being 
part of many very successful products, including several that are on shelves today. In 
addition, a number of tities slated for release in the next few years are also jumping on 
the Lua bandwagon. 

Angband 

Angband is a freeware dungeon-exploration game based on the works of J.R.R. Tolkein 
(Angaband was a citadel constructed by Morgoth in Tolkein's The Silmarillion). 
Angband has been around in one variation or another for quite sometime. Its 
predecessors include Moria (1985) and Rogue (late 1970s). It was originally text-based, 
but now sports some nifty graphics 

There are three main points to keep in mind with Angband. First, it runs on just about 
every platform, including Windows, Windows CE, DOS, Mac, Amiga, OS/2, Linux, 
BeOS, Atari, Solaris, and several others. Seeond, it is considered to be extremely 
addictive. Third, the game stili fits on a 1.44 floppy disk! 

Lua has been added to the C Angband distribution for customizations. There are 
literally dozens of Angband variants, with everything from psionics to multiplayer Iron 
Man adventures added. Lua seripting is available to handle using objects (like wands, 
rods, staves, food, potions, and scrolls) and player spells. Event handling exists for Eua 
functions for in-game events; for instance, Eua Scripts handle which objects Stores in the 
game will buy and sell. 

Angband ean be found Online, at http://www.thangorodrim.net, and is currently 
maintained by Robert Ruhlmann. 

Baldur's Gate 

Bioware used Lua as the primary script engine for its popular game Baldur's Gate. AU 
of the game's debugging commands were exposed to Lua, and the seript engine was 
exposed and available via command line from the game. For Bioware, this allowed a 
deep level of debugging without having to develop extensive debugging tools for the 
engine. For the fans, this allowed a window into the engine that also help spawn 
numerous hacks and independent projects utilizing the Infinity engine. 

Baldufs Gate ean be found on Bioware's site at 
http://www.bioware.eom/games/baldurs gate/ . 

Bioware also used Lua to some extent in another popular game you may have heard of, 
MDK2. 
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Monkey Island 


Lucas Arts was one of the first game studios to really start utilizing Lua. A large amount 
of Grim Fandango, the main adventure game Lueas Arts released in 1997, was written 
in Lua. 

Lua replaeed an in-house seripting engine Lueas Arts used, called SCUMM. Lua was 
also used in the game Monkey Island as the development seript engine. In Monkey 
Island there is a small tribute to Lua—apparently the designers renamed a bar inside the 
game from SCUMM to the Lua Bar. 

Homeworlds 

Relie Entertainmenfs Homeworlds was released with Lua hooks to allow its hardcore 
fans the ability to ereate mods. The resuit was numerous enjoyable mods and haeks 
from the eommunity, ineluding Homeworld variants set in the worlds of Star Trek, 
Babylon 5, Battlestar Galactica, and Star Wars. Relie says they chose Lua for the same 
reasons so many other eompanies do: beeause it is easy to use, performs speedily, and is 
small in size. 

Relie is also working on a new game that uses Lua seripts for its AI deeision engine. 

The plan is for an interpretive AI layer to help programmers test out the different 
behavior easily, and therefore tweak game settings with seripting instead of having to 
do eomplete re-eompiled souree eode builds. Relie ean be found at 
http://www.relic.eom/ . 

Other Games 

There are dozens of other tities that have used Lua. Criterion Studios is one of the larger 
eompanies, located online at http://www.criterionstudios.com . 

Criterion has released several 3D game tities here and in Japan that use Lua as their 
primary game seripting language. The popular fantasy RPG Pem made extensive use of 
Lua, so much so that the eommunity spawned several haeks to the engine overriding 
some of the common Lua files that handled races and classes. Slingshot Game 
Technologies produced a snowboarding game using Lua called Soulride, which ean be 
found Online at http://soulride.com . 

The former chief programmer at Slingshot, Thatcher Ulrich, has written a few open- 
source Lua 2D seript tools (you used one in the last chapter). Now he works for 
Oddworld, which we expect to release an X-Box title any day now. 
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Beyond Lua 

Being the versatile, lightweight ereature that it is, Lua can be found in a number of 
different places, doing any number of different things. Not relegated to just the game 
World, Lua has found its way as a development language into commercial endeavors, 
university projects, and govemment agencies across the world. 

LualDE 

A programming language isn't complete until it possesses an IDE (Integrated 
Development Environment), and thaf s exactly what LualDE is. Developed for the 
community by Tristan Rybak, EualDE is currently (as of this writing) under a beta 1.0 
release, with support for Eua 5.0. It has features for multiple-documents interfacing, 
Windows-build and debugging messages, breakpoints, and call stack trace Windows. It 
also has an API for dynamically loaded Eua extensions. 

Most folks familiar with a graphical development environment will recognize the 
interface right away (see Eigure 8.3). EualDE can be downloaded from 
http://www.gorlice.net.pl/~rvbak/luaide . 

Figure 8.3. The Lua IDE hard at work debugging Gravity 



Plua 

Plua is a port of Eua to the Palm platform. Based on the PalmOS 3.1 and Lua 4.0, Plua 
has much to add to the platform, and is generally a complete distribution, except for a 
few missing pieces of functionality—mainly a few Standard I/O functions, Standard in 
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(stdin) functions, and math functions that would need additional support from third- 
party math libraries. 

Despite the size restrictions for the Palm, Plua adds quite a bit to Lua distribution, 
including 

• Database functions 

• Serial input functions 

• Low-level Palm graphics support 

• New user interface functions for the Palm 

The Plua project itself was was created and copyrighted by Mardcio M. Andrade, and 
documentation and sample code can be found online at 
http://netpage.em.com.br/mmand/pluadoc.htm . 

toLua 

The toLua tool is designed to make integration between Lua and C or C++ code super 
easy. toLua is capable of mapping C-style constants, functions, classes, variables, and 
methods. It also automatically generales the binding code to access these features from 
Lua. Version 5.0 alpha, which corresponds to the 5.0 Release of Lua, is the current 
release as of this writing. The Software package is brought to us by Waldemar Celes, 
and can be found on the Lua Wiki page, at http://www.tecgrafpuc-rio.br/~celes/tolua/ . 
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Summary 

Lua is found in everything from simple 2D puzzles to complicated 3D shoot-em-up 
games, and from small Palm devices to large, industrial seienee projeets. Most 
eommonly, Lua partners with C as the seript of ehoiee to provide an additional interfaee 
of flexibility to the development team, and to add features like level builders and user 
customizations. 

Important points from this ehapter inelude the following: 

• Lua tends to be a ehoiee in eommereial development beeause it is small in size, 
fast, and easy to use. 

• SDL, C, and Lua are often partners in erime. 

• Lua is fairly pervasive aeross the gaming industry. 
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Exercises 


1: Use the Enigma library and sample levels to construet an Enigma level. 

2: Use the sample that ships with the MAD engine to construet a MAD scene. 
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Part FOUR: Programming with Ruby 


This part of the book begins with an overview of Ruby to get you up to speed, then 
moves into Ruby libraries like Rubysdl and FXRuby. Code for a quick-and-easy 
graphics engine written in Ruby appears in Chapter 10. Lastly, some of the more game- 
oriented real-life Ruby projeets are discussed. 
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Chapter 9. Getting Started with Ruby 


They brought me rubies from the mine, And held them to the sun; I said, they are drops 
of frozen wine From Eden's vats that run. 

-Ralph Waldo Emerson 

Eike Chapters 3 and 6, this is a brief introduetion to the language of interest—in this 
ehapter, thafs Ruby. This is a speedy overview ehapter, but it does inelude a few useful 
examples of Ruby eode. 


348 



Debuggers 

Ruby comes with a debugger, accessible on the command line, for stepping through 
problems with programs (see Figure 9.1). Type the following to aeeess it: 


Figure 9.1. Accessing the Ruby command-line debugger 
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Ruby -r debug MyProgramScript.rb 


The debugger has a number of useful eommands for, well, debugging a Ruby program. 
These are listed in Table 9.1. 


Command 

break 

watch 


Table 9.1. Debug Commands 

Use 

Set breakpoint at speeified line or method 
Set a watehpoint for an expression 
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Table 9.1. Debug Commands 


Command 

catch 

delete 

display 

undisplay 

cont 

step 

next 

list 

up 

down 
finish 
trace 
quit 

var global 

var local 

var instance 

var const 

method 

instance 

method 

thread list 

thread 

current 

thread 

thread stop 

thread resume 

P 

help 

else 


Use 

Set a catchpoint for an exception 

Delete breakpoints or watchpoints 

Set display expression to be printed when program stops 

Unset display 

Continue program exeeution 

Step forward in the program until the next souree line 

Step forward in the program until the next souree line. Treat method 
calls as one instruetion 

List line of souree eode 

Seleet staek firame that ealled eurrent stack firame 
Seleet staek firame ealled by eurrent staek firame 
Execute until selected staek frame retums 
Turn traee mode on or off 
Exit debugger 

Show global variables in eurrent staek frame 
Show loeal variables in eurrent staek frame 
Show instance variables of the given object 
Show constants of the given object 
Show methods of the given object 

Show instance methods of the given class or module 
Show thread list 
Show current thread 

Switch to a given thread 
Stop the given thread 
Resume the given thread 

Evaluate the given expression in current stack frame and show its 
value 

Print debug commands 

Evaluate input in the current stack frame and show its value 
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Language Structure 


The most important thing to remember when starting out is that Ruby is considered to 
be a pure objeet-oriented seripting language. Being objeet-oriented means that any data 
itself is treated like an objeet. For instanee, integers in Ruby automatieally beeome 
objeets, instanees of the number elass. 

The Ruby language is eonsidered similar to Perl and PHP. Ruby resembles Perl in a lot 
of ways. For instanee, there are shorteuts to globals using funny eharaeters, like $&, S<, 
$>, and $DEBUG. If you're familiar with string handling and pattern matehing in Perl, you 
will find Ruby's handlings of those same problems to be similar. 

One important differenee between Ruby and other objeet-oriented languages: Ruby only 
supports single inheritanee; most OOP languages have multiple inheritanee. This means 
that in Ruby, sub-elasses ean only be derived from one parent. 

A few lingual notes right off the bat. Each expression in Ruby generally takes up one 
line. There is no need for line terminations in Ruby. Semieolons ean be used at the end 
of a line statement for style, but they aren't neeessary. Ruby will reeognize when a new 
line eomes along, so you ean end a statement by simply hitting Return. Expressions ean 
also be grouped with parentheses. 

Comments in Ruby begin with the pound sign. 

# This is a comment. 

# The interpreter ignores me 


Comments ean also be embedded between =begin and =end eommands; the interpreter 
will also skip anything in between them; 


=begin 

This is a comment 

The interpreter ignores me 

=end 


Without the equal signs, begin and end take the form of a bloek expression, most likely 
to be seen in an exeeption: 


begin 

# This is a block 

# There are normally expressions within 
end 


Ruby supports these eoneepts, ealled bloeks, whieh are designated in a number of 
different ways. Basieally everything within a do and an end is a bloek. Bloeks ean also 
be designated with curly braekets, like so: 

do I this_is_a_block | 
end 
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{this is another block} 


A special Ruby command called yield can call code blocks and evaluate them. yield 
evaluates the block given to the current method with arguments (if no argument is 
given, it uses nil). The argument assignment to the block parameter is done just like a 
multiple assignment. 

Objects, Classes, and Methods 

As Ruby is an objeet-oriented language, it may be useful to defme some objeet-oriented 
terms. An object is a eontainer that holds variables and funetions that are specific to 
itself. Objects are ereated by elasses, and are synonymous with elass instanees. Classes 
are like objeet factories. They eombine an objeet template with its methods. Methods 
are ehunks of eode that return a value of some sort (see Figure 9.2). 

Figure 9.2. Objects and methods derived from a elass 


Class 


Object Constructor 






In praetiee, objeets, elasses, and methods are eombined together. One example of this is 
that objects are ereated by calling elasses with their constructor methods. 

In Ruby, classes take on the following form: 

Class MyClass() 

def initializeO 
end 

def MyMethodl 
end 

# Other Expressions 

# Mayhap a CONSTANT 

end 
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The def expressions inside of MyClass are aetually methods; 

Def MyMethod (arguments) 
expression 

end 

A elass instanee of Myciass (that is, a Myciass objeet) ean be ereated by ealling the 
MyClass eonstruetor, initialize. An initialize method has speeial meaning in 
Ruby; it will automatieally link up with a new method eall. So, to ereate a elass instanee 
of MyClass, just type 

MyObject = MyClass.new() 

Onee MyObject has been ereated, all of Myciass's methods are available to it: 

MyObj ect.MyMethodl 

Ruby has a number of Standard built-in elasses and methods. Many of the common 
elasses are listed in Table 9.2, and common methods are listed in Table 9.3. 


Table 9.2. Built-in Ruby Classes 


Classes 

Domain 

Array 

Ordered collection of objects 

Bignum 

Holds integers outside the range of Fixnum 

Binding 

Encapsulate execution context 

Class 

Base class for all classes 

Continuation 

Objects generated by kernel eall that hold a return address and 
execution context 

Dir 

Represents directories 

Exception 

Carries exception information 

FalseClass 

Base class for logically false 

File 

Abstraction of any file objeet 

File::Stat 

Common status information for file objects 

Fixnum 

Holds integer values 

Float 

Represents real numbers 

Hash 

Collection of key value pairs 

Integer 

Base class for Bignum and Fixnum 

10 

Basis for all input and output 

MatchData 

Type of the speeial S~ variable for encapsulating pattern matches 
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Table 9.2. Built-in Ruby Classes 


Classes 

Domain 

Method 

Base class for method objects 

Module 

Base class for module objects 

NilClass 

Base class for nii 

Numerio 

Base type for Float, Fixnum, and Bignum 

Obj ect 

Parent class for all classes 

Proc 

Parent for object blocks of code that are bound to a set of local 
variables 

Range 

An interval with a start and end 

Regexp 

Holds regular expressions 

String 

Holds byte sequences 

Struet 

Bundles attributes together 

Struet::Tms 

Holds Information on process times 

Symbol 

Object that represents a Ruby name 

Thread 

Parent for thread objects 

ThreadGroup 

For keeping track of threads as a group 

Time 

Abstraction of dates and times 

TrueClass 

Base class for logically true 


Table 9.3. Built-in Ruby Methods 

Method 

DescriptionA¥hat It Does 

' str 

Performs str by a subshell 

Array 

Converts given argument to an array 

at exit 

For cleaning up when the interpreter exits 

autoload 

Specifies a fde to be loaded using require 

binding 

Returns data structure of a binding 

ealler 

Returns the Information of the current call 

eateh 

Exeeutes a throw/catch block 

ehop 

Removes last character of a value 

ehomp 

Removes a line firom a value 

eval 

Evaluates the given expression as a Ruby program 

exee 

Exeeutes the given command as a subprocess 

exit 

Exits immediately 
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Table 9.3. Built-in Ruby Methods 


Method 

DescriptionA¥hat It Does 

exit! 

Exits immediately and ignores any kind of exception handling 

f ail 

Raises exceptions 

Float 

Converts given argument to a float 

f ork 

Forks child and parent proeesses 

format 

Returns a string in the given format 

gets 

Reads a string from Standard input 

global variables 

Returns the list of all the global variable names defined in the 
given program 

gsub 

Searches for a pattern in a string, and if the pattern is found, makes 
a copy of the string with the pattern replaced with a given 
argument 

gsub! 

Searches for a pattern in a string, and if the pattern is found, 
replaces the pattern with the given argument. 

Integer 

Converts given argument to an integer 

iterator? 

Returns true if called from an iterator 

lambda 

Returns newly created procedure object from the block 

load 

Loads and evaluates the Ruby program in the flle 

local variables 

Returns the list of all the local variable names defined in the 
current scope 

loop 

Loops until terminated 

open 

Opens a file and returns a file object associated with the file 

P 

Prints given object to the stdout 

print 

Prints arguments 

printf 

Prints arguments in a given format 

proc 

Returns newly created procedure object from the block 

pute 

Writes a given character to the default output 

raise 

Used for raising exceptions 

rand 

Returns a random number greater than or equal to 0 and less than 
the given value 

readline 

Reads a string from Standard input, raises exception at the end of a 
file 

readlines 

Returns an array containing the read lines 

require 

Used to load modules 

select 

Calis select to rcads, writes, excepts, and timeout system calls 
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Table 9.3. Built-in Ruby Methods 


Method 

DescriptionA¥hat It Does 

sleep 

Causes seript to sleep for a given amount of seeonds 

split 

Splits a string at the given string 

String 

Converts given argument to a string 

sprintf 

Returns a string in the given format 

srand 

Sets the random number seed for rand 

sub 

Searehes a string held in $ for a pattern and makes a copy that 
replaees the first oceurrenee with given argument 

sub! 

Searehes a string held in $ for a pattern and replaees the first 
oeeurrenee with given argument 

syscall 

Used to make system calls 

System 

Runs given command in a subproeess 

test 

Performs a file test 

throw 

Exeeutes a throw/cateh bloek 

trace var 

Sets the hook to a given variable that is ealled when the value of 
the variable is ehanged 

trap 

Specifies the signal handler for a signal 

untrace var 

Deletes hooks set by trace var 


Obviously, Ruby supports inheritance. Inheritance allows classes to inherit functionality 
from each other. A parent elass in this sort of relationship is ealled a super elass, and the 
child elass is ealled a sub elass. Sub classes are defined as ehildren by the less than (<) 
Symbol; 

MySubClass < MyParentClass 

def MyMethod (argumenta) 
expression 

end 


Ruby also supports a number of other OOP coneepts, such as mixins, which simulate 
multiple inheritanee in Ruby's single parent system); singletons, whieh provide a way to 
override objeet ereation; and overloading, whieh is when method calls ean be 
overwritten by new definitions. 

Language Types 

Ruby is case-sensitive, and identifiers can be eomposed of letters of the alphabet, 
deeimals, or the underseore eharaeter. The Standard language types inelude strings, 
eonstants, ranges, and numbers. 
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AU variables and constants in Ruby point at an object. When a variable is assigned or 
initialized, the object that the variable is referencing is also assigned. Variables in Ruby 
are either global variables that begin with the $ character, instance variables that begin 
with an @ character, class variables that start with @@, constants that are all uppercase 
letters, local variables that are all lowercase letters, or class constants that are defined 
within certain classes or modules. There are also a few special variables in Ruby. All of 
these Ruby variables are outlined in Table 9.4. 


Variable 

_FILE_ 

_LINE_ 

@variable 

@@ 

$variable 

variable 

VARIABLE 

false 

nil 

self 

true 


Table 9.4. Ruby Variables 

Description 

Current source filename 

Current line number in the source file 

Instance variable 

Class variable 

Global variable 

Standard variable 

Constant variable 

Instance of the class FalseCiass (i.e. false) 
Instance of the class Niiciass (i.e. false) 
Receiver of the current method 
Instance of the class TrueClass (that is, true) 


Setting a variable is fairly intuitive; it is done like so: 


myvariable = "My String\n" 


Set a global variable like this: 

$myvarible = "My String\n" 


Set class variables like this: 

@@myvariable = "My String\n" 


And so on. 

In Ruby, a handful of reserved words cannot be used for variable names. These include 
the following: 

BEGIN 
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class 


ensure 

nil 

self 

when 

END 

def 

false 

not 

super 
while 
alias 
defined 
for 

or 

then 

yield 

and 

do 

if 

redo 

true 

begin 

else 

in 

rescue 

undef 

break 
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elsif 


module 

retry 

unless 

case 

end 

next 

return 

until 

Strings 

In Ruby, strings are 8-bit byte sequences. They normally hold characters, but can also 
hold binary data. A string object is actually an instance of the class string. 

When playing with strings, one should know that Ruby differentiates between single 
and double quotes. Notice the differenee between 

print "stringXn" 

and 

Print 'stringXn' 


When the two lines of eode above run within the interpreter, Ruby reeognizes the Xn as 
an eseape sequenee on the first line and not on the seeond. 

The explanation for this is that strings ean begin and end with either single or double 
quotation marks, but whether you use single or double quotation marks depends on the 
situation. Expressions in double quotes are generally subjeet to baekslash eseape 
eharaeters, and single quotes are not (exeept for X and XX). If you need a string to not be 
subjeet to any eseape sequences, including the X or XX, then you must begin the 
expression with a percentage % sign. 

The string class has many methods (close to 100) associated with it. Since Ruby must 
often handle strings, it makes sense that it would have many Standard methods for 
performing Standard actions on strings. 

Common eseape sequences are listed in Table 9.5. 
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Table 9.5. Common Ruby Escape Sequences 


Sequence 

Meaning 

\ 

Add octal value character 

\a 

Bell 

\b 

Backspace 

\cx 

Control X 

\C-x 

Control X 

\e 

Escape 

\f 

Eorm feed 

\n 

Newline 

\r 

Carriage return 

\s 

White space 

\t 

Tab 

\v 

Vertical tab 

\x 

Add hexadecimal value character 

\M-x 

Meta X 

\M-\C-x 

Meta control x 


Regular Expressions 

Regular expressions are the tools that Ruby uses for pattem matehing and other 
oommon functions against strings. Not only do eommands exist for matehing pattems, 
but there are also eommands for anehoring patterns, repeating searehes, ehoosing 
between alternate patterns, grouping, and substitution. Common Ruby expressions are 
listed in Table 9.6. 


Expression 

$! 

$@ 

$& 

$' 

$ ' 

$ + 


Table 9.6. Common Ruby Expressions 
Description 

Exeeption Information message (set by raise) 

Baektraee of the last exeeption 

The string matehed by the last sueeessful pattern mateh in this seope 

The string preceding whatever was matehed by the last sueeessful pattern 
mateh in the current scope 

The string following whatever was matehed by the last sueeessful pattem 
mateh in the current scope 

The last bracket matehed by the last sueeessful search pattem 
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Expression 
$ 1 , $ 2 ... 


$~ 

$= 

$/ 

$\ 

$, 

$; 

$. 

$< 

$> 

$_ 

$0 

$* 

$$ 

$? 

$: 

$" 

$DEBUG 

$FILENAME 

$LOAD_PATH 

$stdin 

$stdout 

$stderr 

$VERBOSE 

$-0 

$-a 

$-d 

$-F 

$-i 

$-1 


Table 9.6. Common Ruby Expressions 
Description 

Contains the subpattern from the corresponding set of parentheses in the 
last sueeessful pattem matched 

Information about the last mateh in the current scope 

Flag for case insensitive 

Input record separator 

Output record separator 

Output field separator 

Default separator for string#split 

The current input line number of the last file that was read 

The Virtual concatenation file of the files given by command-line 
arguments. stdin by default 

Default output for print, printf.s by default 

The last input line of string by gets or readline 

Contains the name of the file containing the Ruby script being executed 

Command-line arguments given for the script 

The process number of Ruby running this script 

The status of the last executed child process 

The array contains the list of places to look for Ruby Scripts and binary 
modules by load or require 

The array contains the module names loaded by require 

Status of the -d switch 

Same as $<. filename or stdin filcnamc 

The alias to the $: 

The current Standard input 
The current Standard output 
The current Standard error output 

The verbose fiag, which is set by the -v switch to the Ruby interpreter 
The alias to the $ / 

True if option -a is set 
The alias to the $debug 
The alias to the $;. \ 

In in-place-edit mode 
The alias to the $ : 
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Table 9.6. Common Ruby Expressions 
Expression Description 

True if option -lis set 
True if option -pis set 
The alias to the $ verbose 

Constants 

Like variables, constants hold references to objects and are created when they are first 
assigned. Unlike in other languages, constants can be changed in Ruby, although a 
change fires off a warning from the interpreter. 

Constants that are defined within a class or module are accessible from within the class 
or module. Outside of the class or module, the scope operator (::) can be used to 
access them. Ruby also has a number of pre-defined constants that are global in scope; 
these are listed in Table 9.7. 

Table 9.7. Ruby Global Pre-DeUned Constants 


Constant 

Description 

ARGE 

Alias to $< 

ARGV 

Alias to $ * 

DATA 

The file object of the script 

ENV 

Contains current environment variables 

FALSE 

False 

NIL 

Nil 

RUBY RELEASE DATE 

Ruby release date string 

RUBY PLATFORM 

Ruby platform identifier 

STDIN 

Standard input or $stdin 

STDOUT 

Standard output or $stdout 

STDERR 

Standard error or $stderr 

TRUE 

True 

VERSION 

Ruby version string 

Ranges 
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Ranges are used in Ruby to express sequences such as one through ten or A to Z. 
Ranges come with a number of useful methods for iterating over themselves or testing 
their contents. The .. operator is used to create a range type object: 

myrange = 1..10 


Ranges are probably most often used to create arrays but are also sometimes used in 
conditional statements. 

Numbers 

Ruby deals primarily with integers and floating-point numbers. Smaller numbers are 
objects of the Fixnum class and large numbers are objects of the Bignum class. Ruby 
understands octal, binary, and hexadecimal numbers. Ruby numbers are outlined in 
Table 9.8. 


Table 9.8. Ruby Numbers 


Number 

Type 

10 

Integer 

-10 

Signed integer 

10.10 

Floating point number 

Oxffff 

Hexadecimal integer 

ObOlOll 

Binary integer 

0377 

Octal integer 


As all numbers are objects, you may fmd them used in Ruby in what would be unusual 
ways in other languages. Numbers in Ruby will respond to messages and built-in 
methods that do iterations. 

Ruby has a number of operators, including the Standard +, /, and *. Again, most 

operators are method calls. Following is a list of the Ruby operators, firom highest to 
lowest level of precedence (the operators are further outlined in Table 9.9): 

1 . :: 

2 ** 

3. -(unary) +(unary) ! ~ 

4. /% 

5. +- 

6. « » 

7. & 

8 . 1 ^ 

9. >= < <= 

10 . <=> == ===!==-!- 
11 . && 
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12. II 

13. 

14. =(+=, -=■■■) 

15. not 

16. and or 


Table 9.9. Commonly Used Ruby Operators 


Operator 

Use 


Tests for equality 

=== 

Tests equality in a case statement 

<=> 

Compares two values 

<, <=, >=, > 

Less than, greater than, etc. 


Regular expression pattern mateh 

+= 1 

Incrementby 1 

-=i 

Deerement by 1 

&& 

Logieal and 

11 

Logical or 

1 

Logieal not 

1= 

Not equal 


Range 

: : 

Scope resolution 

and 

Logical and 

eql ? 

Compares type and value 

equal? 

Compares object ID 

not 

Logical not 

or 

Logical or 


Assignments are made in Ruby using the powerful equal sign: 

Helio = 'Hi' 


Multiple assignments ean be made by using commas and equal signs: 
1,2,3 = 'you', 'me' , 'I' 
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Control Structures 


Ruby has a number of Standard control structure expressions for controlling program 
flow. These include if, then, unless, else, while, until, for, and case. These 
Controls are supported by a number of operators in addition to the Standard ==, <, <=, >, 
>=, and =. These operators are listed in Table 9.9. 

The chain of if ... then... else. .. is one of the most common control structures, and in 
Ruby the syntax appears as follows: 

if this is true [then] 
do_this 

[elsif this is true_instead [then] 
do_this_Instead] 

[else 

do this if all else fails] 
end 


A typical unless control structure looks almost identieal: 

unless this is true [then] 
do_this 
[else 

do_this_instead] 

end 


The case statement in Ruby is mueh like a quieker-coding if statement when multiple 
ehoiees are available. The case statement makes a comparison between the expression 
given and any number of expressions (or ranges) that are set after while keywords: 

case $my_case_statement 
when 0 .. 1 "case 1" 

when 2 .. 3 "case 2" 

when 4.. 20 "case 3" 

when Square "case 4 sides" 

else "case_5" 
end 


The until construet and the while construet are also very similar: 

# First until 
until this is true 
do_this 
end 

#Then while 
while this is true 
do_this 

end 
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The for looping construet is used to iterate over any object that can respond to iteration, 
namely arrays or ranges. The following example prints everything listed in the first 
argument given; 


for i in [1, 2, 3] 
print I, " " 
end 


There are a few useful commands that can be used in loops (and in blocks), including 
the following: 

break, Terminates the immediately enclosing loop. 
next, Skips to the end of the loop. 

redo. Repeats the current loop from the start without re-evaluating the condition. 
retry. Repeats the current loop. 

return. Exits the method/loop/block with the return value or an array of return values. 

For handling exceptions Ruby has a built-in raise command. raise can create a 
runtime error, send messages, create an exception of type error_type, and even send 
traceback Information in the format given by a variable caller function. Examples: 


raise "This is an error" 

raise SyntaxError, "invalid syntax" 

raise SyntaxError.new("new error type") 


Arrays and Hashes 

Arrays are instances of the class Array, and they hold collections of object references. 
An array can be created by simply assigning a number of values as you would with a 
variable: 


$MyArray = ['Helio', 'I', 'love', 'you'] 


Each value in the array can then be accessed numerically: 

print $MyArray[0] 
print $MyArray[l] 
print $MyArray[2] 
print $MyArray[2] 


Hashes are also instances of the Hash class, and are also collections of object references. 
Hashes are like arrays, only within curly brackets and with key => value pairs: 

$MyHash = {'a'=>l, 'b'=>2, 'c'=>3, 'd'=>4} 


366 



Then hash values can be referenced by their keys: 


print $MyHash['a'] 
print $MyHash['b'] 
print $MyHash['c'] 
print $MyHash['d'] 


Exceptions 

Ruby has built-in exception classes for raising exceptions, each of which has its own 
message string and stack backtrace. Exception code is normally put into begin and end 
blocks, and is handied by a rescue clause, like this: 


begin 

# code that does something 
rescue Exception 

Sstderr.print "error message" 
raise 

end 


The raise mcthod is uscd in this case to raise the current exception, but it can also be 
used to create a unique exception and error message: 

if MyError == true 

raise MyError, "My Unique Error", caller 
end 


Catch and throw are also used when execution must be abandoned completely. The 
catch command creates a block of code that executes normally until a throwis 
encountered. When Ruby hits a throw, it goes back up the call stack looking for the 
matching catch, rewinds to that point, and terminates the block. Optionally, when Ruby 
jumps back up the stack, another throw parameter can be sent upwards, causing Ruby 
to continue bouncing upward: 


catch (:MyCatch) do 
while (1) 

throw 

end 


end 


:MyCatch unless all is well 


Modules 

Modules are groups of methods, classes, and constants (see Figure 9.3). As programs 
grow bigger and bigger, it becomes necessary for most languages to segregate bits of 
functionality and similar functions. Modules are Ruby's way of organizing large batches 
of code. 
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Figure 9.3. Modules hold groups of classes and methods 




































Save the module into a file ealled MyFile.rb, and Ruby will have the option of loading 
the additional module by using require or load: 

Load "MyFile.rb" 

Require "MyModule" 


Ruby eomes with a number of modules for adding extra funetionality to your program 
already built in (see Table 9.10). 


Table 9.10. Pre-Defined Ruby Modules 


Module 

Use/Description 

Comparabie Comparing objects 

Enumerable Traversal and searehing methods 

Errno 

Mapping OS System errors 

FileTest 

File test operations 

GC 

Garbage collection interface 

Kernel 

Objects can access kernel module 

Marshal 

Ability to serialize objects 

Math 

Basic trigonometry and transcendental functions 

Obj ectSpace Added GC funetionality for iterating over all living objeets 

Precision 

Number precision 

Process 

Manipulate processes 

Libraries 


Libraries are eolleetions of modules and classes, and Ruby has a wealth of them. Table 
9.11 lists a few of the more common libraries and their general purposes. These libraries 
are written in Ruby itself and are found in the /lib/ folder of the distribution. 


Table 9.11. Ruby Libraries 

Library 

Purpose/Description 

Delegate 

For building delegate-type objects 

English 

Includes the English library file 

Observer 

For communication between objects 

Profile 

For code profiling, prints summary of System calls to Sstderr 

NetWork 

Ruby provides a number of socket-level access classes, including socket, 
BasicSocket, IPSocket, TCPSocket, SOCKSocket, TCPServer, and 
UDPSocket 
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Table 9.11. Ruby Libraries 


Library Purpose/Description 

Singleton Por ensuring that only one instance of a particular class is created 
Timeout por timing code blocks 
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Memory, Performance, and Speed 


Ruby suffers from the same speed impediment as the other languages in this book— 
being interpretive and-high level. Ruby's built-in profiler tool helps quite a bit when 
gauging performance by examining code snips and routines for slowdowns. The profiler 
can be called from the command line by adding -r prof ile, or it can be used inside 
code by using require, like so: 

require "profile" 


The profile library will print a summary of the number of calls to each Ruby method in 
the given program and the time spent in each method. This is all printed to $stdout. 

Garbage Collection 

Ruby has a mark and sweep garbage collection system. It periodically sweeps through 
dynamically allocated memory and reclaims it if it isn't in use. Ruby also provides a GC 
(garbage collection) module for interfacing the underlying garbage collection methods, 
which include 

• disable. Disables garbage collection. 

• enable. Enables garbage collection. 

• start, Initiates a garbage run (unless disabled). 

• garbage_collect. Starts garbage collector. 


Speed 

Finally, here are a number of tricks you can use to help speed up Ruby code: 

Check the profiler to see where the code is bogging down. 

Use the built-in GC to take control over garbage collection. 

Initialize variables before they are used. Variables used within a block can be defined 
before the interpreter hits the block. 

When iterating over a large set of elements, declare any iterator variables. 

When returning variables from a block, have the variables pre-initialized so they aren't 
allocated on-the-fly. 

Ruby supports both multiple threads and forks for creating sub-processes. Threads are 
implemented within the interpreter, and forks are invoked in the operating system. 
Either of these can be used for a speed hit in certain cases. 
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Summary 

Before moving on to the next chapter, you should have Ruby installed on your 
computer, and you should feel quite comfortable using Ruby blocks, classes, methods, 
variables, and common control structures like while and if. 

Important points from this chapter: 

• Any form of data in Ruby is an object. 

• An object is a Container that holds variables and functions that are speeific to 
itself. 

• Lowerease letters equal local variables, uppercase letters equal a constant, 
variables that start with $ are global, variables that start with @ are instance 
variables, and variables that start with @@ are elass variables. 

• End-of-line deliminators are not neeessary in Ruby. 
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Questions and Answers 


1: Q: Ack! What does "parse error" mean? 

A: A: It usually means you have a bloek thafs missing an end. 

2: Q: I heard that Ruby is a eompiled language and not interpreted; is this true? 

A: A: There are pians in the future to move Ruby eloser to a eompiled language 
in order to inerease its exeeution speed. 
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Exercises 


1: Define object, class, and method. 

2: What is the difference between a Ruby hash and a Ruby array? How is each 
declared? 

3: Describe two built-in Ruby classes. 
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Chapter 10. Getting Started with Ruby Games 

The price of wisdom is above rubies. 

-Job 28:18 

This chapter covers the common libraries used for game programming in Ruby, 
focusing on Ruby's OpenGL and SDL wrappers. 
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FXRuby 


Ruby comes with a few toolkits, including FXRuby and OpenGL. FXRuby is a Ruby 
interface to the FOX toolkit, which is designed for creating graphical user interfaces and 
which is written in C++. 

The Fox toolkit has a horne at http://www.fox-toolkit.org/ . 

FXRuby and OpenGL for Ruby are partners in many projeets. They are often used 
together, and Fox provides a few widgets for providing OpenGL support. FXGLCanvas 
and FXGLViewer are FXGLVisuai objeets. FXGLVisuai can be used to ereate new visual 
applieations and ineludes options for double buffering (visual_doublebuffer) and 
stereo sound (visual_stereo): 


MyVisualObject = FXGLVisuai.new(MyApplication, VISUAL STEREO) 


The FXGLCanvas widget is an OpenGL window with minimal functionality: 

MyCanvas = FXGLCanvas.new (MyApplication, visual to use) 


The FXGLViewerwidget is a higher-level OpenGL window with more funetionality and 
is built the same way: 


MyViewer = FXGLViewer.new (MyApplication, visual to use) 


There are a number of important differences between the Standard FOX API and the 
aetual FXRuby API. FXRuby uses Ruby strings instead of the Standard Fox FXStrings. 
Since Ruby handles underlying memory management, some of the drudgery of handling 
pointers and arrays in FOX can be skipped. Many of the FOX classes have been 
extended with built-in Ruby methods sueh as each, initiaiize, and catch. There are 
also differences in multi-threading and the return values to a few interfaees. 

With the FXRuby included in the Standard Ruby package comes a number of FXRuby 
samples. These are in the (surprise!) Samples directory. FXRuby is fairly easy to 
include in a Ruby seript. Onee installed, Ruby's require and include eommands can 
be used to bring in the library: 

#!/usr/bin/env ruby 
require "fox" 
include Fox 


A new FXRuby application is declared by calling the FXApp class with its new 
eonstruetor: 

MyApplication = FXApp.new() 
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FXRuby requires a main or parent window; these ean be deelared in the same way using 
the new method of FXMainWindow. This function ties into the newly created 
MyApplication Fox applieation and is also fed the window title: 


main = FXMainWindow.new(MyApplication, "FXWindow") 


You ean ereate a GUI button in the main window by using FXButton: 


FXButton.new(main, "Press This Button!") 


Finally, you must ereate MyApplication with a create method, show it on the sereen 
with a Show method, and then turn it on with a run method: 

MyApplication.create() 
main.Show(PLACEMENT_SCREEN) 

MyApplication.run() 
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Ruby and OpenGL 


I discussed OpenGL first in Chapter 4 , where I introduced PyOpenGL. To briefly 
summarize, OpenGL is a platform-independent API for creating graphics. Ruby's 
OpenGL extension module was developed by Yoshiyuki Kusano. It provides an 
interface to the basic OpenGL, GLU, and GLUT APIs. 

As of this writing, the extension is at Version 0.32b and can be found at Yohshiyukani 
Kusabo's homepage, at http://www2.giganet.net/~voshi . 

GLU is a high-level library that partners with OpenGL. It provides additional 
functionality that would otherwise be fairly difficult to code in just OpenGL. GLUT is 
another OpenGL addition—it's a toolkit for designing OpenGL programs. Together 
these two build an API that allows Ruby to easily aecess OpenGL eommands. 

A simple example of OpenGL is drawing a geometric shape. Step 1 is ineluding the 
OpenGL, GLU, and GLUT libraries if they are necessary. Posix Systems may also need 
the Ruby path—that is, # ! /usr/local/bin/ruby: 

#!/usr/local/bin/ruby 
require "opengl" 
require "glut" 


Using the OpenGL Proc function and its new method will declare a new function, called 
MyTriangie, that can draw a geometrie shape: 

MyTriangle = Proc.new { 


In order to draw the shape, the GL buffer must be cleared, and a new GL object of type 
TRiANGLE must be ereated: 

GL.Ciear(GL::COLOR_BUFFER_BIT) 

GL.Begin(GL::TRIANGLES) 


Then you can set, with gl . Color, the RGB values that you'll use when drawing: 

GL.Color(1.0, 1.0, 1.0) 


And then you need to set the vertices of the three points of the triangle in 2D space: 


GL, 

.Color(1.0, 

1.0 

GL, 

.Vertex(0, 

0) 

GL, 

.Vertex(10, 

10) 

GL, 

.Vertex(10, 

50) 


1 . 0 ) 


The OpenGL buffer must be flushed with gl . Fiush and the calls to OpenGL ended. 
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The whole MyTriangle function looks like this: 

MyTriangle = Proc.new { 

GL.Ciear(GL::COLOR_BUFFER_BIT) 
GL.Begin(GL::TRIANGLES) 

GL.Color (1.0, 1.0, 1.0) 

GL.Vertex(0, 0) 

GL.Vertex(10, 10) 

GL.Vertex(10, 50) 

GL.End 

GL.Flush 


In order to use the function, you must create a window (MyWindow) for display. The 
window can be built using GLUT's CreateWindow method after GLUT is initialized; 

GLUT.Init 

MyWindow = GLUT.CreateWindow("OpenGL Triangle") 


The final steps for actually running this short Ruby OpenGL sample are to use GLUT's 
DisplayFunc method tO display MyTriangle, and thcn call MainLoop tO gct it all 
started: 

GLUT.DisplayFunc(MyTriangle) 

GLUT.MainLoop 


The Standard Ruby install comes with many OpenGL samples located in the 
Ruby\Samples\OpenGL directory. These include examples showing how to draw two- 
dimensional and three-dimensional shapes, play with colors, and rotate objects in three- 
dimensional space. 
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Ruby and SDL 


SDL has been a common thread throughout the book, first in Chapter 4 with the 
Pygame SDL wrapper for Python, and then in Chapter 7 with LuaSDL. It would stand 
to reason that SDL, being the progressive library that it is, also has its fingers in Ruby. 

To use SDL with Ruby, you first need to install the SDL library, which can be found in 
its entirety at its horne page, http://www.libsdl.org . 

Once SDL is installed, Ruby needs an interface into SDL; there are several different 
interfaces to choose from. Most of the interfaces can be found in the Ruby Application 
Archive at http://raa.rubv-lang.org/ . 

To make it a bit easier for Windows users, a bundled SDL package is contained in a 
nifty executable included on this book's CD; it is called pack-rubysdl.exe, and you can 
find it on the CD in the Chapter 10 folder. The pack-rubysdl.exe package is distributed 
under the GNU Public License and, for Win32, includes the following: 

• Ruby 1,6,4, The Ruby version. 

• Rubysdl-0,6, The actual SDL package. 

• Rubywin-0,0,3,2, An IDE for Ruby on Windows platforms. 

• Rb2exe-0,2, A program for converting Ruby Scripts into executable files. 

• Opengl-0,32, The version of OpenGL. 

The package is built with Cygwin and comes with a few SDL samples, including those 
for using the keyboard and joystick, loading sound files from disk, and manipulating a 
CD. The package also includes one fairly complete sample game by Ohbayashi Ippei. 

The caveat to this bundle is that the documentation and installation are in Japanese. You 
will not be able to read the install files without the proper Japanese character set 
installed. This is inconvenient for English speakers, as the install files may look like 
Eigure 10.1, depending on the platform used. 

Figure 10.1. The pack-rubysdl install may look strange without the right 

Japanese character set. 
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Whether your platform displays the characters correctly or not, choosing the left-hand 
confirmatiori button means you agree to install the RubySDL folder and files on your 
C:\ drive (see Figure 10.2). 

Figure 10.2. Choosing the left-hand button at this screen after launching 
.pack-rubysdl.exe willinstall the package. 



Ruby Win is one of the big bonuses in this paekage. A GUI developed by Masaki Suketa 
that bundles Ruby 1.6.4 and Seintilla 1.38 (by Neil Hodgsen), RubyWin ereates an 
environment for running Ruby SDL seripts without having to ehange or manipulate 
loeal environment variables. Launehing the exeeutable brings up the RubyWin GUI (see 
Figure 10.3) and the Run File eommand, aeeessible via the Ctrl-R shortcut or through 
the Ruby menu, can be used to launch and test Ruby SDL applieations 

Figure 10.3. The RubyWin GUI 
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Commonly Used Ruby SDL Modules and Classes 

The common Ruby SDL modules and elasses are listed in Table 10.1. 

Table 10.1. Common Ruby SDL Modules and Classes 


Component 

Module or 
Class 

Description 

SDL::CD 

Class 

Represents the CD-ROM drive 

SDL::Error 

Class 

Error class; handles Ruby/SDE errors 

SDL::Event 

Class 

Handles events 

SDL::Event2 

Class 

Handles events 

SDL::Joystick 

Class 

Represents a joystick 

SDL::Key 

Module 

Defines key constants and gets the key state 

SDL::Mixer 

Module 

Holds sound functions and constants 

SDL::Mixer::Wave 

Class 

Handles WAV files 

SDL::MPEG 

Class 

Handles MPEG streams 

SDL::Mouse 

Module 

Contains mouse constants and functions 

SDL::PixelFormat 

Class 

Parent to sdl: : Surface (obsolctc) 

SDL::Screen 

Class 

Displays the screen image 

SDL::SKK 

Class 

Handles Japanese input 

SDL::Surface 

Class 

Contains methods for creating SDE surfaces 
(images) 

SDL::TTF 

Class 

Handles TrueType fonts 

SDL::WM 

Module 

Handles Windows 


Ruby SDL ineludes all sorts of elasses for supporting window management, MPEG 
streaming, joysticks, CD-ROMs, and different fonts. More commonly used are the tools 
for initializing and SDL environments, creating SDL surfaces, handling events, audio, 
time, and Japanese character support. 

Initializing SDL 

The init module is used to initiate SDL. A flag that triggers which portion of SDL 
needs to be initialized is included when initializing: 

SDL::INIT_AUDIO. Initialize system audio. 

SDL::INIT_VIDEO. Initialize system video. 

SDL::INIT CDROM, Initialize the CD-ROM. 
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SDL::INIT_JOYSTICK, Initialize a joystick device. 

The line of eode that will initialize video looks like the following: 

SDL.init(SDL::INIT_VIDEO) 

A partieular game's video mode is set with sdl . set_video_mode (), whieh takes as 
arguments the width and height of the sereen, bits-per-pixel (0=s eurrent or loeal 
display), and any neeessary flags: 

SDL.set_video_mode(640, 480, 0, SDL_FLAG) 

Possible flags for sdl. set_video_mode include the following: 

SDL::SWSURFACE. Creates video surfaee in system memory. 

SDL::HWSURFACE, Creates video surfaee in video memory. 

SDL::FULLSCREEN. Attempts to use the full sereen. 

SDL::SDL_DOUBLEBUF. Enables double buffering. 

To fmd out if a partieular video mode is supported, there is also an 
SDL. checkvideoMode () oommand that uses the same syntax. 

Surfaces 

After setting up a video mode, sdl :: Surface. new will ereate an empty SDL surfaee. 
Its new method also keeps an eye out for several flags: 

SDL::SWSURFACE, Creates the surfaee in system memory. 

SDL::HWSURFACE, Creates the surfaee in video memory. 

SDL ::SRCALPHA, Chooses the loeation with the best hardware alpha support. 

SDL::SRCOLORKEY. SDL ehooses the loeation with the best hardware colorkey 
blitting. 

Surfaee. new also needs width, height, and format. The format must be the instanee of 
SDL:: Surfaee and have the same bits per pixel as the speeified surfaee. 

There are dozens of methods that can be used on SDL surfaees. Some of the more 
eommonly used ones are listed in Table 10.2. 

Table 10.2. Common SDL Surfaee Methods 
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Method 

Equivalent To 

Purpose 

alpha 


Returns surface alpha 

bpp 


Return bits per pixel 

colorkey 


Returns surfaee eolorkey 

drawCircle 

draw circle 

Draws a eirele 

drawEllipse 

draw ellipse 

Draws an ellipse 

DrawFilledCircle 

draw filled circle 

Draws a eirele filled with speeified 
eoior 

drawFilledEllipse 

draw filled ellipse 

Draws an ellipse fdled with speeified 
eoior 

drawLine 

draw line 

Draws a line between the given 
eoordinates 

drawRect 

draw rect 

Draws a rectangle 

displayFormat 

display format 

Makes a eopy of itself on a new 
surfaee; used for fast blitting 

displayFormatAlpha 

display format alpha 

As displayFormat wtlh alpha value 
per pixel 

fillRect 

fili rect 

Filis given rectangle with speeified 
color 

f lags 


Returns surface flags 

format 


Returns pixel format 

getClipRect 

get clip rect 

Returns clipping rectangle for the 
given surface 

getPalette 

get palette 

Returns the palette of the speeified 
surface 

GetPixel 

get pixel 

Gets color of the speeified pixel 

GetRGBget rgb 


Returns RGB component values of 
speeified pixel in an array 

getRGBA 

get rgba 

Like getRGB, but includes an alpha 
value 

h 


Return height 

load 


Loads image (such as a BMP) and 
returns instance of sdl: : Screen 

loadBMP 

load bmp 

Loads given bitmap 

lock 


Sets up a surface for directly 
accessing pixels 

makeCollisionMap 


Creates a collision map 

mapRGB 

map rgb 

Maps the RGB color value to the 
pixel format of speeified surface and 
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Table 10.2. Common SDL Surface Methods 


Method 

Equivalent To 

Purpose 

returns the pixel value as an integer 

mapRGBA 

map rgba 

Same as MapRGB but also includes an 
alpha value 

mustLock? 

must lock? 

Returns true if surface must be locked 
to directly access pixels 

put 


Draw given image in self 

PutPixel 

put pixel 

Writes pixel to the specified position 

rotateScaled 

Surface 

rotate 

scaled surface 

Rotates surface instance with given 
angle and scale. Note; method is 
considered obsolete; if s been 
SUperceded by transformSurface. 

rotateSurface 

rotate surface 

As rotateScaledSurface but SCale 
is set to 1.0 

saveBMP 

s ave bmp 

Saves file in BMP format 

setAlpha 

set alpha 

Used to set alpha and per-pixel alpha 
blending 

setColorKey 

set color key 

Sets the colorkey of a blit-able 
surface 

setColors 

set colors 

Same as setPalette but with 
different flags 

setPalette 

set palette 

Sets a portion of the palette for the 
given 8-bit surfaee 

transformSurface 

transform surface 

Creates a rotated and scaled image of 
given surface 

unlock 


Unlocks a surface 

w 


Returns width 

Events 



Ruby SDL has two event classes, eventand event2, for handling events. Eaeh has a 
number of methods; these methods are outlined in Tables 10.3 and 10.4. 


Table 10.3. Event Methods 

Method 

Equivalent To 

Purpose 

appState 

Event.app state 

Returns current 


stat.enableUNICODE 
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Table 10.3. Event Methods 


Method 

Equivalent To 

Purpose 

Event.enable Unicode 

Enable UNICODE 

Keyboard translation (disabled by 
default) 

Event.disableUNICODE 

Event.disable Unicode 

Disables Unicode keyboard 
translation 

Event.enableUNICODE? 

Event.enable Unicode? 

Returns whether Unicode 
keyboard translation is enabled 

gain? 


Returns true when gaining focus 

inf o 


Returns event information in an 
array 

keyMod 

key mod 

Returns the current key modifiers 

keyPress? 

key press? 

Returns true when a key is pressed 
down in a key event 

keySym 

key sym 

Returns SDL Virtual key sym 

mouseButton 

mouse button 

Returns the mouse button index 

mousePress? 

mouse press? 

Returns true during a mouse 
button down event 

mouseX 

mouse X 

Returns the x coordinate of the 

mouse 

mouseXrel 

mouse xrel 

Returns the relative mouse motion 
on the x-axis 

mouseY 

mouse y 

Returns the y coordinate of the 
mouse 

mouseYrel 

mouse yrel 

Returns the relative mouse motion 
on the y-axis 

new 


Creates a new sdl: : Event object 

poli 


Polis for currently pending events 

type 


Returns the type of a given stored 
event 

wait 


Waits for the next available event 

appState 

app state 

Returns the kind of ActiveEven 


Table 10.4. Event2 Methods 

Equivalent To Purpose 

Event that occurs when 
mouse/keyboard focus gains/loss 


Method 

Active 
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Table 10.4. Event2 Methods 

Method Equivalent To Purpose 

appState Event2.app_state Same as Event.appState 

enableUNICODE enable_unicode Same aS Event.enableUNICODE 

enableUNICODE? Event2.enable_unicode? «ame aS Event.enableUNICODE? 


disableUNICODE disable Unicode 
JoyAxis 

JoyBall 

JoyButtonDown 

JoyButtonUp 

JoyHat 

KeyDown 

KeyUp 

MouseButtonDown 

MouseButtonUp 

MouseMotion 

poli 

quit 

SysWM 

VideoResize 

Walt 


Same as Event.dlsableUNICODE 

Event that oeeurs when axis of joystiek 
is moved 

Event that oeeurs when a joystiek 
traekball moves 

Event that oeeurs when joystiek button 
is pressed 

Event that oeeurs when joystiek button 
is released 

Event that oeeurs when joystiek hat 
moves 

Event that oeeurs when a key is pressed 

Event that oeeurs when a key is 
released 

Event that oeeurs when a mouse button 
is pressed 

Event that oeeurs when a mouse button 
is pressed 

Event that oeeurs when the mouse is 
moved 

Same as Event.poli 

Event that oeeurs when a quit or exit 
is requested 

Event that oeeurs when plaform- 
dependent window manager oeeurs 

Event that oeeurs when Windows are 
resized 

Same as Event.wait 


Ruby SDE also has mouse and key elasses and methods for mouse and keyboard events; 
these are outlined in Table 10.5. 
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Table 10.5. Mouse and Keyboard Events 


Method 

Equivalent To 

Purpose 

Key.disableKeyRepeat 

Key.disable key repeat 

Disables key repeat 

Key.enableKeyRepeat 

Key.enable key repeat 

Sets keyboard repeat rate 

Key.getKeyName 

Key.get key name 

Returns the string of key name 

Key.modState 

Key.mod state 

Returns the current of the 
modifier keys 

Key.press? 


Return true if given key is 
pressed 

Key.scan 


Scans key state 

Mouse.hide 


Hides mouse cursor 

Mouse.setCursor 

Mouse.set cursor 

Used to change the mouse cursor 

Mouse.Show 


Shows a mouse cursor 

Mouse.state 


Returns mouse state in array 

Mouse.warp 


Sets the position of the mouse 
cursor 


Audio 

Ruby's SDL has a Mixermodule that is used to serve up music fdes, ehange volume, and 
set up sound effects like fading. Mixerhas a class for handling WAV files, 

SDL : : Mixer : : Wave, and a elass for loading musie, SDL : : Mixer : : Music . Wave 
handles Standard WAV fdes, while Music can load mod, S3M, it, XM, MID, and MP3 
tile formats. Mixer's methods are outlined in Table 10.6. 


Table 10.6. Mixer Methods 


Method Equivalent To Purpose 

allocateChannels allocate_channels Dynamieally change the number of ehannels 


fadeInMusic 
fadeOutMusic 
halt N/A 
haltMusic 
load 


fade in_music 
fade_out_music 

halt music 


managed by the mixer 
Fade in the given music in milliseconds 
Fade out the given music in milliseconds 
Halt playing of a particular channel 
Halt music 

Load a music tile and return the object of 

Mixer::Music 


open 

play? 


Initialize SDL_mixer 

Return whether specitic channel is playing 
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Table 10.6. Mixer Methods 


Method 

Equivalent To 

playChannel 

play channel 

playMusic 

play music 

playMusic? 

play music? 

pause 


pause? 


pauseMusic 

pause music 

pauseMusic? 

pause music? 

resume 


resumeMusic 

resume music 

rewindMusic 

rewind music 

setVolume 

set volume 

setVolumeMusic 

set volume mi 

spec 



Purpose 

or not 

Play a WAV on a specific channel 
Play music 

Return whether the music is playing 

Pause on a particular channel 

Return whether a partieular ehannel is 
paused 

Pause musie 

Return whether the musie is paused 

Resume a particular channel 

Resume music 

Rewind music 

Set the volume 

Set volume 

Return the audio spec in array 


Time 

SDL uses the notion of ticks to keep traek of time. The getTicks/get_ticks method 
will get the number of milliseeonds that have passed sinee SDL was initialized. There is 
also a delay method that will wait a given number of milliseeonds before returning; it is 
used to proeess scheduled jobs and events. 

Japanese Input 

Ruby's SDL comes equipped with an SSK module for eneoding the Japanese eharaeter 
set. This module relies on the SDLSSK library, and ean set the eneoding to the Japanese 
eharaeter system (EUCJP), the ASCII-preserving Unieode System (UTF8), or the Shift- 
JIS Japanese system (SJIS). SSK has a handful of methods; these are outlined in Table 
10.7. 


Method 

Context 

Dictionary 

eneoding 


Table 10.7. SSK Methods 
Purpose 

Super elass that represents the state of input 
Super elass for manipulating user dietionaries 
Returns eneoding 
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Table 10.7. SSKMethods 


Method Purpose 

Eucjp Sets encoding to EUCJP 

Keybind Represents the keybind in SDLSKK input system 

RomKanaRuleTable Represents the rule of conversion from Alphabet to Japanese kana 
sJis Sets eneoding to SJIS 

UTF8 Sets eneoding to UTF8 


A Sample Ruby SDL Program 

AU of the tables given in this ehapter aren't enough—^you need to try an example of 
using SDL and Ruby together. In the Chapter 10 seetion of the aeeompanying CD is a 
sample RubyBounee folder with five Ruby files. They are as follows: 

. CONST.RB 
. PLAYER.RB 
. RUBYBOUNCE.RB 
. STATE.RB 
. SYSTEM.RB 

These five files are explained in the next few subseetions. Eaeh has a part to play in 
setting up a quiek SDL Ruby environment where a player manipulates a small bouneing 
ruby (see Figure 10.4). 

Figure 10.4. A bouneing ruby is dispiayed in the RubyBounee program. 
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This program can be run from the RubyWin applicatiori. Open up rubywin.exe in your 
new C:\RUBYSDL\BIN folder, choose the Ruby menu, select Run, and then choose the 
RUBY-BOUNCE.RB file. 

The CONST.RBFile 

The simplest of the live Ruby files, CONST.RB is used to hold any speeific game 
eonstants that need to be defined (see Figure 10.5). In this example, the file holds four 
constants, each of which defines a wall in the playing surface. Changing these values 
later on ehanges where the player can travel onscreen: 

Figure 10.5. File reiationship for RubyBounce 
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LWALL_X=40 
RWALL_X=600 
FLOOR_Y=440 
CEIL Y=60 


These values are x- and y-set pixel ranges that define the edges of the playing surface in 
pixels (see Figure 10.6). 


Figure 10.6. Playing field x andy boundaries. 
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The SYSTEM.RB File 

The functions set up in the SYSTEM.RB file should look familiar, as they are similar to 
the funetions you used in earlier ehapters. The only differenee between the first def ine, 
setup_bmp, and earlier endeavors to load bitmaps is Ruby's own unique twist: 

def Setup bmp(filename) 

graph=SDL::Surface.loadBMP(filename) 
graph.setColorKey SDL::SRCCOLORKEY, graph[0,0] 
graph=graph.displayFormat 
end 


Here sdl :: Surface. loadBMP is used to grab a .BMP file, the eolorkey is set with the 
setColorKey method, and finally, displayFormat is used to display the surfaee. 

Also ineluded in this file are two funetions for keeping traek of where an objeet travels 
in the two-dimensional sereen. The x out funetion and the send_loc function help 
determine if the objeet tries to travel past the lwall and rwall eonstants set in 
CONST.RB; 

def x_out?(x,w) 

x+w+10<LWALL_X II x-10>RWALL_X 
end 

def send_loc?(x,w) 

return true if LWALL_X+SEND_FIELD_WIDTH>x+w 
return true if RWALL_X-SEND_FIELD_WIDTH<x 
false 
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end 


Then you define the System class with the initialize and continue_game methods. In 
a full version game, this would be a good place to set important variables like player 
score and number of lives, but in this case just one instance variable is set; @iife: 

class System 

def initialize 
@life=3 
end 

def continue game? 

@life > 0 
end 

end 


The STA TE.RB File 

There are three classes defined in STATE.RB; state, stateinitializer, and 
stateDriver. Each is uscd to kecp track of the game state, and each is stored within the 
jt (just in time) module. The state class has two methods, initialize and 
move_state. State. initialize is probably the most important method in this script. 

It first calls the constructor and sets three important instance variables: state hash, 
state_driver, and state. Using cach variable, state . initialize then sets a loop 
that iterates over each entry in state_hash: 

class State 

def initialize(first state) 
state_initializer = Stateinitializer.new 
yield state initializer 

@state hash = state initializer.state hash 
@state driver = StateDriver.new(self) 

@state = first_state 

@state_hash. each do |k;ey,val| 
self.instance eval <<-EOS 
def self.#{key.id2name}(*arg) 

if @state_hash[:#{key.id2name}][@state] then 

@state_hash[:#{key.id2name}][@state].call(@state_driver,*arg) 

end 

end 

EOS 

end 

end 


The move_state mcthod is uscd to crcatc new States and assign them to @ state: 

def move_state(new_state) 

@state=new_state 

end 
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The stateinitiaiizer class defines both initialize —^which creates the 
state_hash instance variable—and add_event: 

class stateinitiaiizer 
def initialize 
@state_hash={} 
end 

attr_reader :state_hash 

def add_event (state, event, Sbloclc) 

if not @state_hash[event] then 
@state_hash[event]={} 
end 

@state_hash [event] [state] =block; 

end 

end 


Finally, define the elass StateDriver with two methods, initialize and move_state: 

class StateDriver 

def initialize(state_obj) 

@state_obj =state_obj 
end 

def move_state(new_state) 

@state_obj.move_state(new_state) 

end 

end 


The PLA YER.RB File 

Now the fun stuff—the player must be defined with a eonstruetor method 
(initialize). You need methods to display the player onsereen (w, h, and draw) and 
move around the sereen (act and move_lr). But first, the PLA YER.RB file needs help 
from SYSTEM.RB and STATE.RB; 

require 'System.rb' 
require 'state.rb' 


Next, designate the elass piayerand define a few player constants: 

class Player 
INIT_DY=-50 
DX=2 0 
H=32,-1^1=32 
G=2 0 

GRAPH P1 = Setup bmp 'ruby.bmp' 

These eonstants initialize the height and width and name of the bitmap image of the 
player pieee. After that, call the initialize method. This method not only ealls the 
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SYSTEM.RB code but it also establishes keyboard events for moving the playefs ruby 
piece around the screen, including moving left and right and jumping the piece up: 


def initialize(system) 

@system=system 

@x=320;@y=200 

@dy=0 

@state=JT::State.new(:jumping) do |i| 

i.add_event(:walking,:act) do |d,key,dt| 
move_lr(key,dt) 
if key.jump then 
@dy= INIT_DY 
d.move state :jumping 
end 
end 


The player pieees must also traek the constants set in CONST.RB so that the pieee 
eannot leave the playing field: 

i.add_event(:jumping,:act) do |d,key,dt| 
move_lr(key,dt) 

@y += @dy*dt/100 

@dy += G*dt/100 
if @y > FLOOR_Y - H then 
@y = FLOOR_Y - H 
d.move state rwalking 
end 
end 


Included in the Player. initialize method are sample event handlers to traek the 
player pieee in ease it eollides with any other sprites/rects on the playing surfaee: 

@damage_state = JT::State.new(:normal) do |i| 
i.add_event(:normal,:act) { } 

i.add_event(:normal,:collision enemy) do |d| 

@system.collision enemy 
@ damage_time=0 
d.move_state(rdamaged) 
end 

i.add_event(:damaged,:act) do |d,dt| 

@damage_time+=dt 

d.move state(:normal) if @damage time > DAMAGE TIME 
end 

i.add_event(:damaged,:collision enemy) { } 

end 

end 


After Player. initialize eome two quiek methods that define the width and height of 
the player pieee: 


def w ;W;end; 
def h ;H;end; 
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You need a draw method to put the previously defined bitmap (in graph_pi) onto the 
screen. Drawing the bitmap is accomplished with the put method: 

def draw(screen) 

screen.put(GRAPH_P1,@x,@y) 

end 


The act method is a worker method that cheeks with STATE,RB and estabhshes the 
state. act and damage_state. act instanee variables so that the player pieee has the 
functionality from STATE.RB: 

def act(key,dt) 

@state.act(key,dt) 

@damage_state.act(dt) 
end 


Einally, define the player's movement within a move_lr method. Move_lr cheeks 
whether the playeds key presses move the actual game pieee off of the predefined 
playing surface: 

def move_lr(key,dt) 

@x-=DX*dt/100 if key.left 
@x+=DX*dt/100 if key.right 
@x = LWALL_X if @x< LWALL_X 
@x = RWALL_X-W if @x > RWALL_X-W 
end 


The RUBYBOUNCE.RB File 

It's in REFBYBOETNCE.RB that SDL is opened and initialized and the actual game loop 
runs. Eirst, SDE and the other defined files are required: 

require 'sdl' 
require 'System.rb' 
require 'state.rb' 
require 'const.rb' 
require 'player.rb' 


Initialize SDL with its init method, define the video mode, and establish the surface 
area with the following two lines: 

SDL.init( SDL::INIT_VIDEO ) 

screen = SDL::setVideoMode(640,480,16,SDL::SWSURFACE) 


A new structure is established that holds each keypress available to the player: 

Key = Struet.new("Key",:left,:right,:jump,:send) 
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The n 0 w method. constructor is Ccillcd. for euch object thut must bc initmbzecii 


system=System.new 
player=Player.new(system) 
event=SDL::Event.new 
k;ey=Key. new 


Now that every object you need is established, the game loop is created. First, use tick 
to establish the time: 

before=now=SDL:rgetTicks-l 


Then establish a whiie loop that uses the poii method to check for events firom the 
keyboard: 

whiie System.continue_game? 
if event.poli != 0 then 

if event.type==SDL::Event::QUIT then 
break 
end 

if event.type==SDL::Event::KEYDOWN then 
exit if event.keySym==SDL::Key::ESCAPE 
end 
end 


Each possible key press is queried for by Key: rpress?: 

SDL::Key::scan 


key.left = 

SDL: 

Key::press? 

(SDL: 

Key: 

LEFT) 

key.right 

= SDL 

:Key::press 

? (SDL 

: Key 

:RIGHT 

key.jump = 

SDL: 

Key::press? 

(SDL: 

Key: 

UP) 

key.send = 

SDL: 

Key::press? 

(SDL: 

Key: 

DOWN) 


The SDL ticks are checked for in the loop as time moves forward: 


before=now 
now=SDL:rgetTicks 
dt=now-before 


Any actions are fulfilled by calling player. act: 
player.act(key,dt) 

The screen is filled, and the player redrawn with each iteration of the loop: 

screen.fillRect(0,0,640,480,0) 
player.draw(screen) 


398 




AU that is left to do is make sure the SDL screen is flipped and that any garbage is 
collected: 

Obj ectSpace.garbage_collect 
screen.flip 


399 



Summary 

Thafs a wrap on the common Ruby game libraries. A few important points to take from 
this chapter are as follows: 

• Ruby distributions commonly come equipped with pieces needed to make games 
and GUIs, and it is common to find FOXRuby and Ruby OpenGL. 

• Python, Lua, and Ruby each have tools for using SDL and OpenGL. 

• SDL and OpenGL in Ruby look really similar to SDL and OpenGL in other 
languages. 

• There are a number of significant differences to how FOX is implemented in 
Ruby than in other languages. 
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Questions and Answers 


1: Q: What platforms does RubySDL operate on? 

A: A: Linux, Win32, FreeBSD, and BeOS. 

2: Q; How do I use threads in RubySDL? 

A: A: RubySDL eannot handle SDL threads. However, Ruby's threads ean be 
used instead. 
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Exercises 


1: List three common Ruby SDL surface methods. 

2: FXRuby is most commonly used to_. 

3: Use the PLAYER.RB code as a sample to create an OBSTACLE.RB script 
that can add obstacles to the RubyBounce code. 
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Chapter 11. The Ruby Game Community 

The gem cannot be polished without friction, nor man perfected without trials. 

-Chinese proverb 

Ruby is probably the least entrenched of the languages within English-speaking game- 
development companies. It is found much more often in the seientifie and researeh 
eommunity than in the game and entertainment industries. This doesn't mean that Ruby 
ean't be found hard at work in the game field, though—it's been a part of a number of 
large-scale projects involving games. This chapter highlights a few Ruby projects 
associated with games or game-related technologies. 
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Ruby and Game Engines 


Ruby is available as a tool for a few game-programming engines. ClanLib is an engine 
IVe mentioned before that has been used on many independent projeets, while MUES is 
a new Ruby tool known primarily as the backbone of The FserieMUD World. 

ClanRuby 

ClanLib ( www.clanlib.or g) is one of the more popular libraries for amateur game 
designers today. ClanLib is written entirely in C++ as a graphics and game library. It 
takes the hard-to-develop functionality like sound mixing, DirectDraw, networking, and 
working with images and provides an easy-to-use, multi-platform library to develop this 
functionality. ClanLib also provides low-level interfaces to other popular libraries such 
as DirectLB, DirectX, OpenGL, and XI1. 

ClanRuby is a set of bindings from Ruby that tie into ClanLib's library. ClanLib and 
ClanRuby are licensed under the GNU Library General Public License. ClanRuby was 
developed by Russell Olsen, and, as of this writing, Version 0.6.5a—^which is 
compatible with ClanLib 0.6.5—is available at its Sourceforge project page at 
http://sourceforge.net/proiects/clanrubv/ . ClanRuby's horne page—which shows the 
latest ClanRuby developments, offers a brief ClanRuby tutorial and shows sample 
ClanRuby uses—is at http://clanrubv.sourceforge.net . 

ClanRuby 0.6.5 is also included on this book's CD in the Chapter 11 folder. Russell 
Olsen has tested the platform primarily on Red Hat Linux 7.3 using ClanLib 0.6.5 and 
Ruby 1.6.7 or 1.6.5. ClanRuby can be installed from the source by unpacking the tar 
files, running the Ruby configuration script (LXTCONL.RB), which creates the make 
file, and then running make and then make install. 

While ClanRuby currently only works in Red Hat, ClanLib delivers a platform- 
independent interface. If a game is written with ClanLib, it should be possible to 
compile the game under just about any platform without changing the application 
source code. 

But ClanLib is not just a wrapper library, providing a common interface to low-level 
libraries such as DirectLB (Direct Frame Buffer), DirectX, OpenGL, XI1, and so on. 
While platform independence is ClanLib's primary goal, it also tries to be a service- 
minded game SDK. In other words, a lot of effort has been put into designing the API in 
order to ensure that ClanLib is easy to use but stili quite powerful. 

ClanRuby can be brought into a Ruby program after installation with the following: 

require 'ClanRuby' 
include ClanRuby 


Setting up the ClanRuby environment is accomplished with a few init methods and 
Display. setvideoMode, which sct the screen size and resolution. Cleanup is handled 
by deinit methods: 
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#Initialize 
SetupCore.init () 

SetupDisplay.init() 

#Set Display 640x480x16bit 

Display.setVideoMode( 640, 480, 16, false ) 
# 

#Actual Bulk of the program here 
# 

#De-initialize 
SetupDisplay.deinit() 

SetupCore.deinit() 


Users of ClanLib will recognize the upcoming code. Those who have delved into 
OpenGL and SDL in earlier chapters will also find ClanLib's syntax familiar; for 
instance, here's how to draw a rectangle; 

Display.fillRect() #Parameters to define where rect is drawn go here 
Display.flipDisplay() 


Sourceforge is also horne to a few games written in ClanLib, including a Boulderdash 
clone called Epiphany written by Guiseppe D'Aqui; if s at 
htttp://epiphanv.sourceforge.net . 

MUES 

The MUES (Multi-User Environment Server) is a game-environment server written in 
Ruby. The purpose of MUES is to facilitate building online multiplayer games or 
simulations. It provides game worlds in the form of dynamically programmed object 
environments, machine Services and daemons for creating in-game Systems, and a 
network client to access these environments. 

MUES is just the first half of the project—the programming of the server platform. 
MUES is also tied into a MMORPG (Massively Multi-player Online Role-Playing 
Game) called EaerieMUD, which is the Creative, vision-inspired, story-based world the 
development team has been building in conjunction with the engine. 

MUES itself is open-source Software that was released to the public in late 2001. The 
source code and documentation can be found at http://mues.faeriemud.org/ . The MUES 
engine supports a number of useful MUD features, including: 

• Multi threading 

• I/O abstraction 

• NetWork sockets and protocols 

• Object persistence 

• Logging 

• Dynamic/data driven environment 

• User authentication 
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Ruby and Graphics 

Because Ruby is the new kid on the block, a number of the graphical Ruby projects are 
stili very much under construction. The projects I will present in the next subsections 
have been around for a while, have proven their usefulness in a number of applications, 
and can be found packaged with good examples and documentation. In contrast to 
Python and Lua libraries, Ruby graphio librarios tend to be scientific or Web-based in 
nature. 

FXRuby 

I offered a quick look at this toolkit and OpenGL in Chapter 10. In addition to working 
with OpenGL, FXRuby can also work with Scintilla—or at least with FXScintilla, 
which is FOX's wrapper around the Scintilla library. 

More Information on FXRuby can be found at its Website, at http://www.fxrubv.org/ 

Ruby/PGPlot 

Ruby/PGPlot is a Ruby interface to the PGPlot graphics library. PGPlot is, itself, a 
device-independent graphics package specifically designed for plotting graphs of 
publication quality. PGPlot is not public domain Software, but it is available free of cost 
for non-commercial endeavors. It also has hooks into several other languages, including 
Ada, C, FORTRAN, and Python. Ruby/PGPLot relies on Numerio Ruby; the 
technologies and URLs are 

• Ruby/PGPlot, http://www.ir.isas.ac.ip/~masa/rubv/pgplot/index.html . 

• Numeric Ruby, http://www.ir.isas. ac.ip/~masa/rubv/index-e.html#pgplot . 

• PGPlot, http://www.astro.caltech.edu/~tip/pgplot/ . 

RubyDCL 

RubyDCL is a Ruby interface, written by T. Horinouchi, K. Kuroi, and K. Goto that 
hooks into the DCL scientific-graphics library. The interface supports all of DCL— 
every function and subroutine—and, although much of the documentation is in 
Japanese, it does come with some English-language documents and support. Ruby DCL 
is part of a larger project, the Dennou Ruby Project, the purpose of which is to develop 
a suite of Software that facilitates visual scientific simulations. 

The DCL graphics library was originally written in FORTRAN and later ported into C, 
and Ruby DCL is actually the second version of the product built by Dennou. The first 
library, AdvancedDCL, was the experimental prototype for RubyDCL and is now 
obsolete. 

RubyDCL, the Dennou Ruby Project, and the RubyDCL project page can be found 
Online at the following li nk s: 

• RubyDCL, http://rubv.gfd-dennou.org/products/rubv-dcl/ . 

• Dennou Ruby Project, http://rubv.gfd-dennou.org/ . 
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• RAA RubyDCL Project Page, http://raa.rubv- 
lang.org/list.rhtml?name=rubvdcl . 

Libgd-Ruby 

GD is a library by Thomas Boutell that is used for dynamically creating graphic images, 
particularly PNG and JPEG images, and Libgd-Ruby is a package extension library that 
allows Ruby to wrap around GD. Libgd is written in C, and is considered freeware. It is 
dependent on several other libraries, including libc6, the GNU C Library, LreeType 2, 
the GD Graphics Library, and The Independent JPEG Group's JPEG runtime library. 
Details can be found at the following li nks : 

• Libgd-Ruby, http://packages.debian.org/unstable/graphics/bbgd-rubv.html . 

• GD Library, http://www.boutell.com/gd/faq.html . 
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Ruby and Games 

Ruby is the newcomer in the American game industry, but gamers can expect many 
good things to come. Ruby is perfeci for Intemet-based games such as FaerieMUD, 
which is highlighted below. 

The FaerieMUD Project 

Built in tandem and integrated with MUES, The FaerieMUD project is built to be story- 
rich, with a focus on detail, realism, and imagination—^unlike the all-too-common 
violent fantasy world. 

FaerieMUD was originally written in Perl and was ported over to Ruby to take 
advantage of a few Ruby features like built-in meta classes, striet encapsulation, and 
pure OOP. 

The FaerieMUD Project is stili being built, and can be found at 
http://www.faeriemud.org/ . 

The MUFS engine can be found online at http://mues.faeriemud.org/ . 
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Beyond Ruby 

Ruby is the shining star in a few other domains besides game graphics and game 
engines. A few of these are listed in the following sections. 

The Snack Sound Toolkit for Ruby 

The Snack Sound Toolkit is a collection of sound- and voice-processing routines and 
includes tools for speech recognition, formant tracking and synthesis, and other fun 
sound-and speech-based tools. The toolkit, written by Stephen Legrand, is used to 
extend scripting languages and enable such tools within them; Ruby is its prodigy pilot- 
child. 

The original implementation of Snack was inspired by Kare Sjolander and was extended 
to Tcl/Tk. Snack for Ruby leverages the existing Tk graphics and provides direct 
support for waveforms and spectrograms. 

Snack for Ruby requires that the Snack package and Tcl/Tk be installed. RPMs that 
combine both Snack and Tcl/TK in one install are available for Linux users, and the 
toolkit runs on both Posix and Windows environments. 

Snack for Ruby is stili under development but was presented at the International Ruby 
Conference. 

The toolkit can be found on Sourceforge at http://sourceforge.net/proiects/rbsnack/ . 

rbwrap 

rbwrap is a tool for converting Ruby Scripts and programs into standalone executables. 
The tool is in Alpha currently but works for Windows Systems. The package re lies on 
Cygwin and the Gnu C Compiler. 

rbwrap is written by Robert Feldt and can be found at the author's Website, at 
http://www.ce.chalmers.se/~feldt/rubv/applications/rbwrap . 

Memeoize 

Memeoize is a tool for speeding up program execution. It does so by caching functions, 
increasing the size of the running program but also speeding up execution time. 
Memoize is also the brainchild of Robert Feldt; it relies on Cygwin and is meant to 
work with Ruby 1.6.2. 

Memeoize is available online at 

http://www.ce.chalmers.se/~feldt/rubv/extensions/memeoize . 
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Summary 


Thafs a wrap on Ruby. I hope you enjoyed your stay. A few important points to take 
from this chapter: 

• Even though Ruby tools appear more frequently and are used more often in the 
seientific world than in the entertainment and game industries, they ean stili be 
found if you look hard enough. 

• Ruby has quite a bit of support for developing seientific graphs and charts. 
Integration with some of the libraries that allow the rapid development of Ruby 
GUIs makes Ruby a good tool for a number of research facilities. 
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Questions and Answers 


1 : Q; Where can I find more Ruby projects? 

A: A; The Ruby community updates a Web page with active Ruby projects at the 
Ruby Application Archive at http://raa.rubv-lang.org/ . 

2 : Q: Have there been many games written with Clanlib? 

A: A: Clanlib has been involved in dozens of games, and most of them are listed 
on the Clanlib Web site at http ://www. clanlib. org/games .html/ . 
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Exercises 


1: List three available resources for programming games in Ruby. 
2: Finish this statement: "The Snack toolkit deals mostly with_ 
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Part FIVE: The Wrap Up 

The book wrap-up discusses taking what youVe leamed so far into other areas. The 
main topies are using extension as a teehnique in development and wrapping high-level 
languages into C. 
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Chapter 12. Using Python, Ruby and Lua in Development 

The game is up. 


-William Shakespeare, Cymbeline 

High-level languages are capable of working with other programming tools. Discussed 
in this ehapter are eommon ways these languages ean be brought in to work as part of a 
team. TU eover, with examples, extension and wrapping, as well as integrating the 
languages with C. 
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High-Level Languages in the Development Cycle 

There are a number of advantages for using a high-level language in a development 
projeet. These advantages inelude 

• Automated garbage eolleetion. 

• High-level features like built-in pattem matehing and built-in types. 

• Simpler syntaetieal rules. 

• Coding is less time-eonsuming. 

• Lower eosts than using an intemally built language. 

• High-level languages are easily embedded, modular, and extensible. 

• Artists, level designers, and even employees with little eomputer Science 
experience can easily grasp and understand high-level languages. 

There are also a number of reasons to not use a high-level language for a development 
projeet. These include 

• They are slower. 

• Their byte-code can be easier to hack. 

• Their debuggers aren't as advanced. 

• Legal concerns could arise when using open-source code in for-profit 
development. 

The key, then, is to know when to use the tools and when not to use the tools. Although 
Python, Lua, and Ruby can be used to write complete games, they usually aren't. In a 
typical shop they serve a specific function, where their strengths can be leveraged. 

For instance, in a Python game, the main looping engine code may look something like 
the following: 

# Update any input from the User 
Input.Getinput() 

# Process user Input 
Input.Processinput() 

# Use tick to up-date the graphics scene 
Graphics.Tick() 

#Redraw the graphics 
Graphics.Redraw() 


There is nothing that says each of the calls must be Python, however. Python can be 
calling to modules written in other languages. The Graphics. Tick and Redraw 
methods could be ANSI C or even assembly. Python could be running the game loop 
and calling out to C only when needed for CPU-intensive operations. 

In a projeet that mixes languages, you'll likely see two languages, as shown in Figure 
12.1. One will be high-level, used for generic tasks, and administrative. The low-level 
language is used for specific time-saving tasks (see Table 12.1). 

Figure 12.1. Typical roles ofpartnered languages 
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Table 

Typical High-Level Language 

Call low-level language 
Game code default 
AI 

User interfaee 


12.1. Partnered Languages 

Tasks Typical Low-Level Language Tasks 

CPU intensive tasks 
Graphics/rendering system 
Collision deteetion 
Tasks with many quiek iterations 


Perhaps the biggest benefit to development is using a seripting language to drive data. 
Over the years, eompanies have diseovered that it is not a good idea to bury game 
parameters— like movement speed, character strength, and unit hit points for 
example—deep down in executable code. If these attributes are buried, play testing 
becomes an extremely lengthy process because every little change must be made to 
complex, difficult-to-read-and-understand code, and then there must be a lengthy 
recompilation and re-building of the entire game. Rebuilding a game with a large code 
base from scratch can take hours, or even a whole day, and the act of recompiling 
actually risks introducing new bugs or issues. 

If game parameters (like movement speed, character strength, and unit hit points) can 
instead be controlled with a seripting language, they can be changed almost on-the-fly. 
Play testers could change statistics and attributes until the balance of the game makes 
sense without having to go back to a development team. 

Also, game play details can be really time-consuming to program in C or C++. If high- 
level seripting is running the AI, the player attributes, or the quest flow of the game, 
then the C coder will be freed up to focus on the engine code. Designers can easily 
fiddle with the settings of the higher-level code and try out parameters that they 
normally would have to delve deep into the engine to get to. 
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Even better, if the separation between the engine and the game code is severe enough, 
the base low-level engine can actually be used for multiple games and multiple releases 
The C/C++ engine stays static while the high-level seripts define new parameters, new 
game objeets, and new goals and missions for the new player eharaeters. Sinee many 
companies claim that the biggest problem they face is resource management, you can 
see why many have adopted this release philosophy. 
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Extending Python, Lua, and Ruby 


Extending is one of the super powers Python, Lua, and Ruby have to offer. Extending is 
basieally the ability to eombine eode from two or more different languages into one 
running exeeutable or seript. Although this adds a layer of eomplexity to a projeet, it 
gives a developer the ability to piek and ehoose from the existing toolbox. 

AU of these languages are built around being extensible; extensibility is one of the 
features that has made them so prolifie. The language doeumentation that eomes with 
each ineludes a nifty sample and explanation of how to partner with other languages, so 
this seetion is more of a brief overview of the proeess. 

Languages are extended for many different reasons. A developer may want to use an 
existing C library or port work from an old projeet into a new development effort. Often 
extensible languages are used as prototypes, and then profding tools are used to see 
what parts of the eode exeeute slowly, and where pieees should be re-written. 

Sometimes a developer will need to do something that just isn't possible in the main 
language, and must turn to other avenues. 

Extending is mainly used when another language can do the job better—better meaning 
more effieiently or more easily. Most eommonly, you will find these languages 
partnered with C and C++, where the Cs are running eode that needs to be optimized for 
speed and memory. 

Problems with Extending 

As Tve already mentioned, multilanguage development adds an extra layer of 
eomplexity. Partieular problems with extending are as follows: 

• You must debug in two languages simultaneously. 

• You must develop and maintain glue eode that ties the languages together (this 
might be signifieantly large amounts of eode). 

• Different languages may have different exeeution models. 

• Objeet layouts between languages may be eompletely different. 

• Changes to one side of the eode affect the other side, ereating dependencies. 

• Eunetions between languages may be implemented differently. 

Extended programs ean also be diffieult to debug. Eor instanee, Ruby uses the GNEl 
debugger, whieh ean look at eore dumps but stili doesn't have breakpoints or aeeess to 
variables or online souree help. This is really different from the types of tools available 
for C and C++, where breakpoints and eore dumps ean be watehed and managed during 
debug exeeution. Sinee the tools ean differ between two languages, a developer may 
have to hunt through more than one debugger to find a problem. Also, beeause high- 
level language debuggers are usually more primitive, there is less eheeking during 
eompile time, whieh eould lead to missed eode defieiencies. 

There are some glue eode paekages that solve some of these problems. These are third- 
party programs that manage the ereation of extended eode; Simple Wrapper Interfaee 
Generator (SWIG, eovered later in the chapter) is one example of sueh a paekage. 
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Though adding more than one language to a project gives you more options, as I said, it 
does add an extra level of eomplexity. When you add a language, you will need multiple 
eompliers and multiple debuggers, and you will have to develop and maintain the glue 
code between the two languages. Whether to add a language is a tough management 
question, one that needs to be answered based on the needs of eaeh particular project. 

A final issue with having high-level code in a shipped product is that the code reveals 
much more about the source than does C or C++; this can make it more vulnerable to 
hacking. This doesn't mean that C or C++ cannot be hacked, just that if the variable 
names and function names are shipped in Scripts with the game code in a high-level 
format, the game can be easier to break into or deconstruct. 

Extending Python 

There are a few built-in ways of integrating Python with C, C++, and other languages. 
Writing an extension involves creating a wrapper for C that Python imports, builds, and 
can then execute. Python also provides mechanisms for embedding, which is where C 
(or an equivalent) is given direct access to the Python interpreter. There are also a 
number of third-party integration Solutions. 

Writing a Python Extension 

You must write a wrapper in order to access a second language via a Python extension. 
The wrapper acts as glue between the two languages, converting function arguments 
from Python into the second language and then returning results to Python in a way that 
Python can understand. For example, say you have a simple C function called 

function: 

int function (int x) 

{ 

/*code that does something useful*/ 

} 


A Python wrapper for function looks something like the following: 

#include <Python.h> 

PyObject *wrap_function(PyObject *self, PyObject *args) 

{ 

int X, resuit; 

if (!PyArg ParseTuple(args, "i:function" , &x)) 
return NULL; 
resuit = function(x); 
return Py BuildValue("i" , resuit) ; 

} 


The wrapper starts by including the Python.h header, which includes the necessary 
commands to build a wrapper, and also a few Standard header fdes (like stdio.h, 
string.h, ermo.h, and dstlib.h). 

NOTE 
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TIP 


Python commands that are included with Python.h almost always begin with Py or py, 
so they are easily distinguished from the rest of the C eode. 

The PyObject wrapper wrap_function has two arguments, self and args (see Figure 
12.2). The self argument is used when the C function implements a built-in method. 
The argsargument beeomes a pointer to a Python tuple objeet eontaining the 
arguments. Eaeh item of the tuple is a Python objeet and eorresponds to an argument in 
the ealfs argument list. 

Figure 12.2. The illustra ted wrap_ fun c t± on 



The small "i" in the i: functionline is short for int. If the function instead required a 
different type, you would need to use a different letter than "i": 
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• i. For an integer. 

• I. For a long integer. 

• s. For a eharacter string. 

• c. For a single eharaeter. 

• f. For a floating point number 

• d. For double 

• 0 . For an object 

• Tuple, Python tuples ean hold multiple objeets. 

Together, PyArg_ParseTupie () and PyBuiidvaiue () are what eonverts data between 
C and Python (see Figure 12.3). Arguments are retrieved with PyArg_ParseTuple, and 
results are passed back with Py_BuildValue. Py_BuildValue () returns any values as 
Python objeets. 

Figure 12.3. Data converting between C and Python 



PyArg_ParseTuple () is a Python API function that eheeks the argument types and 
eonverts them into C values so that they ean be used. It returns true if all arguments 
have the right type and the components have been stored in the variables whose 
addresses are passed. If a C function returns no useful argument (i.e. void), then the 
Python function must return None. 

In the code snippet an ifstatement is also used. This structure is there just in case an 
error is detected in the argument list. If an error is detected, then the wrapper returns 

NULL. 

Once a wrapper has been written, Python needs to know about it. Telling Python about 
the wrapper is accomplished with an initialization function. The initialization function 
registers new methods with the Python interpreter and looks like this: 

Static PyMethod exampleMethods[] = { 

{"function", wrap_function, 1}, 

{NULL, NULL} 

}; 


void initialize function(){ 

PyObject *m 

m = Py InitModule("example", "exampleMethods"); 

} 
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Only after a wrapper and an initialization function exist can the code compile. After 
compilation, the function is part of Python's library directory and can be called at any 
time, just like a native Python module. 

You can also use a setup fde when importing a module. A setup fde includes a module 
name, the location of the C code, and any compile tags needed. The setup file is then 
pre-processed into a project file or makefile. 

The compile and build process for extending varies, depending upon your platform, 
environment, tools, and dynamic/static decision-making, which makes the Python 
parent documentation extremely valuable when you're attempting this sort of 
development. 

Guido Van Rossum has a tutorial on extending and embedding Python within the 
language documentation, at http://www.pvthon.org/doc/current/ext/ext.html . 

The Python C API Reference manual is also extremely helpful if C or C++ is your 
target language. It's at http://www.python.org/dev/doc/maint22/api/ api.html . 

The last step in Python extension is to include any wrapped functions (in this case, 
function) in the Python code. Do this with a simple import line to initialize the 
module, like so: 

import ModuleToImport 


Then the function can be called from Python just like any other method. 


ModuleToImport.function(int) 


Embedding Python 

Embedding in Python is where a program is given direct access to the Python 
interpreter, allowing the program the power to load and execute Python Scripts and 
Services. This gives a programmer the power to load Python modules, call Python 
functions, and access Python objects, all from his or her favorite language of comfort. 

Embedding is powered by Python's API, which can be used in C by including the 
Python. h header file. This header 

#include "Python.h" 


contains all the functions, types, and macro definitions needed to use the API. 

It is fairly simple to initialize Python in C once the Python header file is included (see 
Eigure 12.4): 


Figure 12.4. The embedding Python process 
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int main () 

{ 

Py Initialize (); 

PyRun SimpleFile("<filename>"); 
Py Finalize (); 
return(); 

} 


Py_initialize is the basic initialization function; it allocates resources for the 
interpreter to start using the API. In partieular, it initializes and ereates the Python sys, 
exceptions, builtin_, and main modules. 

NOTE 

CAUTION 

Py_initialize searohes for modules assuming that the Python library is in a fixed 
loeation, whieh is a detail that may need to be altered, depending on the operating 
System. Trouble with this function may indicate a need to set the operating system's 
environment variable paths for pythonhome or python path. Altemately, the module 
paths can be explicitly set using PySys_SetArgv (). 

The Pyrun_simpleFilefunction is simply one of the very high-level API functions that 
reads the given file from a pointer (file *) and executes the commands stored there. 
After initialization and running any code, Py_Finalize releases the internal resources 
and shuts down the interpreter. 


Python's high-level API functions are basically just used for executing given Python 
source, not for interacting with it in any significant way. Other high-level functions in 
Python's C API include the following: 
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• Py_CompileString(), Parses and compiles source code string. 

• Py_eval_input, Parses and evaluates expressions. 

• Py_file_input, Parses and evaluates files. 

• Py_Main(), Main program for the Standard interpreter. 

• PyParser_SimpleParseString(), Parses Python souree code from string. 

• PyParser_SimpleParseFile(). Parses Python souree eode from file. 

• PyRun_AnyFile(). Retums the resuit of running PyRun_interactiveLoop or 
PyRun_SimpleFile(). 

• PyRun_SimpleString(), Runs given command string in _main_. 

• PyRun_SimpleFile(), As PyRun_simpieString except source code can be read 
from a file instead of a string. 

• Py_single_input, Start symbol for a single statement. 

• PyRun_InteractiveOne(). Read and exeeute a single statement from an 
Interactive deviee file. 

• PyRun_InteractiveLoop(). Read and exeeute all statements from an Interactive 
deviee fde. 

• PyRun_String(), Exeeute souree code from a string. 

• PyRun_File(). Exeeute source eode from a file. 

The high-level tools really just scrateh the surfaee, and Python's API allows memory 
management, object ereation, threading, and exception handling, to name a few things. 
Other eommonly used eommands inelude Pyimport_importModule () , whieh is for 
importing and initializing entire Python modules; PyObj ect_GetAttrString (), whieh 
is for accessing a given modules attributes; and PyObj ect_SetAttrString (), whieh is 
for assigning values to variables within modules. 

Third-Party Integration 

So what happens when there is a large integration projeet and some 100+ C functions 
must be gift-wrapped for Python? This ean be a time-eonsuming, tedious, error-prone 
projeet. Imagine now that the library goes through a major update every four to six 
months, and eaeh wrapper funetion will need to be revisited. Now you know what job 
seeurity looks like! 

Euekily, there are other options available for extension besides wrappers. SWIG, for 
instance, is an extension wrapper designed to make extension easier. It can be used to 
generate interfaces (primarily in C) without having to write a lot of eode. Another 
option is Sip, a relative of SWIG, whieh foeuses on C++. The Boost.Python library is 
yet another tool that ean be used to write small bits of eode to ereate a shared library. Of 
these three, SWIG is the most popular, probably beeause it plays well not only with C, 
C++, Python, and Ruby, but also with Perl, Tcl/Tk, Java, and C#. SWIG is copyrighted 
Software, but it is freely distributed. It is normally found on UNIX but will also operate 
on Win32 OSs. 

SWIG automates the wrapper proeess by generating wrapper code from a list of ANSI 
C functions and variable declarations. The SWIG language is aetually fairly complex 
and very complete. It supports preprocessing, pointers, classes, inheritance, and even 
C++ templates. 
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SWIG is typically called from a command prompt or used with NMAKE. Modules can 
be compiled into a DLL form and then dynamically loaded into Python, or they can be 
set up as a custom build option in MS Development Studio. SWIG can be found online 
at Sourceforge (http://swig.sourceforge.net/) , and Boost.Python, by David Abrahams, 
can be found online at Python.org ( http://www.pvthon.org/cgi- 
bin/moinmoin/boost 2epvthon) . 

Extending Lua 

Lua was built to partner with other languages, and it can be extended with functions 
written in C just as Python can. These functions must be of the lua_CFunction type: 

typedef int (*lua_CFunction) (lua_State *L); 


A C function receives a Lua state and retums an integer that holds the number of values 
that must return to Lua (see Figure 12.5). The C function receives arguments from Lua 
in its stack in direct order. Any return values to Lua are pushed onto the stack, also in 
direct order. 


Figure 12.5. Representation ofLua and Cpartnership 



When registering a C function to Lua, a built-in macro receives the name the function 
will have in Lua and a pointer to the function, so a function can be registered in Lua by 
calling the lua_register macro: 

lua_register(L, "average", MyFunction); 


Values can be associated with a C function when it is created. This creates what is 
called a C closure. The values are then accessible to the C function whenever it is 
called. To create a C closure, First push the values onto the stack, and then use the 
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lua_pushcclosure command to push the C function onto the stack with an argument 
containing the number of values that need to be associated with the funetion: 

void lua pushcclosure (lua State *L, lua_CFunction MyFunction, int 
MyArgument); 


Whenever the C funetion is ealled, the values pushed up are loeated at speeifie pseudo- 
indiees produeed by a maero, lua_upvalueindex. The first value is at position 

lua upvalueindex ( 1 ), the seeond at lua upvalueindex (2 ) , and SO on. 


Lua also provides a predefmed table that ean be used by any C eode to store whatever 
Lua value it needs to store. This table is a registry and is really useful when values must 
be kept outside the lifespan of a given funetion. This registry table is pseudo-indexed at 
LUA_REGiSTRYiNDEX. Any C library ean store data into this table. 

Extending Ruby 

Extending Ruby in C is aeeomplished by writing C as a bridge between Ruby's C API 
and whatever you want to add on to Ruby (see Figure 12.6). The Ruby C API is 
eontained in the C header file ruby.h, and many of the eommon API eommands are 
listed in Table 12.2. 


Figure 12.6. The Ruby CAPI 



Ruby and C must share data types, whieh is problematie when Ruby only reeognizes 
objeets. For C to understand Ruby, some translation must be done with data types. In 
Ruby, everything is either an objeet or a referenee to an objeet. For C to understand 
Ruby, data types must be pointers to a Ruby objeet or aetual objeets. You do so by 
making all Ruby variables in C a VALUEtype. When value is a pointer, it points to one 
of the memory struetures for a Ruby elass or objeet strueture. value ean also be an 
immediate value sueh as Fixnum, Symbol, true, false, or nil. 


A Ruby objeet is an alloeated strueture in memory that eontains a table of instanee 
variables and other elass Information. The elass is another alloeated strueture in memory 
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that contains a table of the methods defined for that class. The built-in objects and 
classes are defined in the C APTs header file, ruby.h. Before wrapping up any Ruby in 
C, you must include this fde: 

#include "ruby.h" 


You must de fine a C global function that begins with init_ when writing new classes 
or modules. Creating a new subclass of Ruby's object looks like the following: 

void Init MyNewSubclass () { 

cMyNewSubclass = rb_define_class("MyNewSubclass", rb_cObject); 
} 


ob j ectis represented by rb_cOb j ect in the ruby.h header fde, and the class is defined 
with rb_def ine_class. Mcthods Can bc addcd tO the class using rb_def ine_method, 
like so: 


void Init MyNewSubclass() { 

cMyNewSubclass = rb_define_class("MyNewSubclass", rb_cObject); 
rb define method(cMyNewSubclass, "MyMethod", MyFunction, value 


Ruby and C can also directly share global values. This is accomplished by first creating 
a Ruby object in C: 

VALUE MyString; 

MyString = rb str new(); 


Then bind the objecfs address to a Ruby global variable: 

Rb define variable("$String", SMyString); 


Now Ruby can access the C variable MyString as Sstrlng. 

You may run into trouble with Ruby's garbage collection when extending Ruby. Ruby's 
GC needs to be handled with kid gloves when C data structures hold Ruby objects or 
when Ruby objects hold C structures. You can smooth the way by writing a function 
that registers the objects, passing free (), calling rb_global_variable () on each 
Ruby object in a structure, or making other special API calls. 

Once code has been written for an extension, it needs to be compiled in a way that Ruby 
can use. The code can be compiled as a shared object to be used at runtime, or it can be 
statically linked to the Ruby interpreter. The entire Ruby interpreter can also be 
embedded within an application. The steps you should take depend greatly on the 
platform on which the programming is being done; there are instructions for each 
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method on the online Ruby library reference, at http://www.rubv- 
lang.org/en/20020 107.html . 


The C API, however, is quite large, and for English users the best source for 
doeumentation is likely the souree code itself 


Table 12.2. Common Ruby C Language APIs 


Type 

API Command 

Function 

char 

rb id2name() 

Returns a name for the given ID 

ID 

rb intern() 

Returns an ID for a given name 

int 

Check SafeStrO 

For raising SecurityError 

int 

OBJ FREEZE() 

Marks the given object as frozen 

int 

OBJ FROZENO 

For testing if an object is frozen 

int 

OBJ TAINT 0 

Marks the given object as tainted 

int 

OBJ TAINTEDO 

For testing if an object is tainted 

int 

rb block given p() 

Returns true if yield would execute a 
block in the current context 

int 

rb cvar definedO 

Returns Qtrue if the given class variable 
name has been defined, otherwise returns 

Qfalse 

int 

rb safe level() 

Returns the current safe level 

int 

rb scan args() 

Scans the argument list and assigns them in 
a similar way to scanf 

int 

rb secure() 

Raises SecurityError if level is less than 
or equal to the current safe level 

VALUE 

rb_apply() 

Function for invoking methods 

VALUE 

rb ary entryO 

Returns an array element at a given index 

VALUE 

rb ary new () 

Returns a new array 

VALUE 

rb ary new2( ) 

Returns a new (long) array 

VALUE 

rb ary new3 () 

Returns a new array populated with the 
given arguments 

VALUE 

rb ary new4 () 

Returns a new array populated with the 
given C array values 

VALUE 

rb ary push( ) 

Pushes a value onto the end of an array 

self 

VALUE 

rb ary pop () 

Removes and returns the last element from 
an array 

VALUE 

rb ary shift ( ) 

Removes and returns the first element from 
an array 
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Table 12.2. Common Ruby C Language APIs 


Type API Command 

VALUE rb ary unshiftO 
VALUE rb_call super() 

VALUE rb_catch() 

VALUE rb_cv_get() 

VALUE rb cvar get() 

VALUE rb define classO 
VALUE rb_define class_under() 
VALUE rb define module() 

VALUE rb define module under() 
VALUE rb_each() 

VALUE rb funcallO 
VALUE rb_funcall2() 

VALUE rb funcall3() 

VALUE rb gv get() 

VALUE rb_gv set() 

VALUE rb hash aref() 

VALUE rb hash aset() 

VALUE rb hash new() 

VALUE rb iterate() 

VALUE rb ivar get () 

VALUE rb ivar set() 

VALUE rb iv get() 

VALUE rb iv set() 

VALUE rb rescueO 

VALUE rb_str_dup() 


Function 

Pushes a value onto the front of an array 

self 

Calis the current method in the super class 
of the current object 

Equivalent to Ruby catch 

Returns class variable name 

Returns the class variable name from the 
given class 

Defines a new top-level class 

Defines a nested class 

Defines a new top-level module 

Defines a nested module 

Invokes the each method of the given 
object 

Invokes methods 

Invokes methods 

Invokes methods 

Returns the global variable name 

Sets the global variable name 

Returns element corresponding to given 
key 

Sets the value for a given key 
Returns a new hash 

Invokes method with given arguments and 
block 

Returns the instance variable name from 
the given object 

Sets the value of the instance variable 
name in the given object to a given value 

Returns the instance variable name 

Sets the value of the instance variable 
name 

Executes until a standardError exccptlon 
is raised, then executes rescue 

Returns a new duplicated string object 
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Table 12.2. Common Ruby C Language APIs 


Type API Command 

VALUE rb str cat() 

VALUE rb_str_concat() 

VALUE rb str new() 

VALUE rb str new2() 

VALUE rb str splitO 

VALUE rb thread create() 

VALUE rb_yield() 

void rb_ary_store() 
void rb_bug() 
void rb_cvar_set() 

void rb_cv_set() 
void rb define alias() 
void rb define_attr() 

void rb_define class variableO 
void rb define constO 
void rb define global constO 
void rb_define_global functionO 
void rb define hooked variableO 

void rb define methodO 

void rb_define module functionO 

void rb define_readonly_variable() 

void rb define singleton methodO 
void rb define variableO 

void rb define Virtual variableO 


Function 

Concatenates length characters on string 

Concatenates other on string 

Returns a new string initialized with length 
eharaeters 

Returns a new string initialized with null- 
terminated C string 

Splits a string at the given deliminator and 
returns an array of the string objeets 

Runs a given funetion in a new thread 

Transfers exeeution to the iterator bloek in 
the eurrent eontext 

Stores a value at a given index in an array 

Terminates the proeess immediately 

Sets the elass variable name in the given 
elass to value 

Sets the elass variable name 

Defines an alias in a elass or module 

Creates aeeess methods for the given 
variable with the given name 

Defines a elass variable name 

Defines a eonstant in a elass or module 

Defines a global eonstant 

Defines a global funetion 

Defines funetions to be ealled when 
reading or writing to variable 

Defines an instanee method 

Defines a method in the given elass 
module with the given name 

Same as rb define variable exeept is 
read-only from Ruby 

Defines a singleton method 

Exports the address of the given objeet that 
was ereated in C to the Ruby namespaee as 
a given name 

Exports a virtual variable to the Ruby 
namespaee 
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Table 12.2. Common Ruby C Language APIs 


Type 

API Command 

Function 

void 

rb exit() 

Exits Ruby with the given status 

void 

rb extend objectO 

Extends given object with module 

void 

rb fatal() 

Raises a fatal exeeption 

void 

rb include module() 

Ineludes the given module into the elass or 
module parent 

void 

rb iter break() 

Breaks out of the enclosing iterator bloek 

void 

rb notimplement() 

Raises a NotlmpError exeeption 

void 

rb raise() 

Raises an exeeption 

void 

rb set safe levelO 

Sets the current safe level 

void 

rb sys fail() 

Raises a platform-specific exeeption 

void 

rb throwO 

Equivalent to Ruby throw 

void 

rb undef methodO 

Undefines the given method name in the 
given elass or module 

void 

rb warn() 

Unconditionally issues a warning message 
to Standard error 

void 

rb warning() 

Conditionally issues a warning message to 
Standard error 
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Python versus Lua Versus Ruby 

So which of the three languages is the best to use on your projeci? That depends a great 

deal on what you want to accomplish. To wrap up the book, Tve outlined some of the 

pros and cons of each language in this section. 

Python Pros and Cons 

The pros of Python are as follows: 

• Python has more extension modules than the other languages. 

• Many online Python tutorials exist. There are also plenty of English books and 
reference materials, many sample Scripts exist online, and there is a wealth of 
introductory material. The Python.org Website is a good place to start looking 
for these because it has sections for beginners, tutorials, guides organized by 
topic, and lists of links and references. 

• Most folks really enjoy the syntax of the Python language because it appears 
clean and is easy to read. 

• Python has an edge where libraries are concerned. There are many libraries, and, 
for the most part, they are well documented. 

• Lots of tools that tie into Python are available, and they are often easier to find 
than the tools for Lua and Ruby. 

The cons of Python are as follows: 

• Existing Python debuggers are considered quirky and slow. Debugging support 
on Macintosh and consoles is even weaker. 

• It can be difficult to bundle Python with other languages. There are lots of 
binary DLLs, and Python has (compared to the other languages) a large Standard 
distribution. 

• Lots of folks really dislike the white space sensitivity of Python syntax. 

• Python can be quite slow at times, as everything is an objeci on the heap. 

Lua Pros and Cons 

The pros of Lua are as follows: 

• Lua is probably the fastest of the three languages and usually uses the least 
amount of runtime memory. 

• Lau has the smallest memory footprint for bundling. 

• The Lau C API is very well documented and has good examples for integrating 
with C. 

The cons of Lua are as follows: 

• The documentation has improved but is stili a bit sketchy overall. Of the three 
languages, Lua it is probably the least documented (the API being the 
exception), with the least amount of code comments. This makes for the largest 
ramp-up time to learn, and there isn't much in the way of introductory Lua 
material. 
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• There isn't a lot of built-in funetionality for Lua. There is little support if you 
need to ereate a large, complex applicatiori. 

• Lua could use a better garbage collector—the current development is moving 
towards that now. Right now, Lua GC uses a very simple and traditional simple 
mark and sweep. 

Pros and Cons of Ruby 

The pros of Ruby are as follows: 

• Ruby possesses fairly good advanced debuggers. 

• Ruby is object oriented from the ground up, and programmers who are OOP 
enthusiasts or who are used to the OOP paradigm will find the language 
extremely comfortable. 

• Ruby has arguably the simplest syntax, with no real rules exceptions. Especially 
true for OOP enthusiasts. 

The cons of Ruby are as follows: 

• Lack of English documentation. 

• Eewer existing works and samples for games than with the other languages. 
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Summary 

Programming is tuming more and more into an everyman's tool. Every single day, 
Software beeomes easier for everyone to use. High-level languages are behind this 
ineredible movement in Game programming. Today, beeause of these ineredible 
languages, games are released with hooks, eustomizable engines, their own languages, 
and modifiable graphics. This ean be aceomplished in development using a data-driven, 
partnered game design model. 

A few important points to take firom this ehapter: 

• There are a number of things to eonsider before ineluding high-level languages 
in a development project. 

• Extending a high-level language ean allow two or more languages to really 
foeus on what they are good at in a single projeet, but it adds a layer of 
eomplexity. 

• Extending is a similar proeess in Python, Eua, and Ruby. 
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Exercises 


1: How do you call an objecfs method from C using Python? Lua? Ruby? 

2: Write sample code to extract C values from one of the three languages' object. 
Watch out for types! 

3: List two possible issues when using extensions in a project. 
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Appendix A. History of Computer Programming 


The following table outlines the history of computer programming through its 
(arguably, in some cases) most important events. 


Year 

Around 
4000 BC 

Around 
3000 BC 

Around 
800 AD 

1612- 

1617 

1622 


1786 


1822 


1834-35 


1840s 


1842 


1847-49 


1853 


1854 


1941 


1944 


Table A.I. A BriefHistory of Programming 

Event 

Clay tablets are used to keep track of transactions. 


Abacus invented in Babylonia. 

The Chinese start to use the number 0, although some historians believed it 
was introduced from India. 

John Napier uses the decimal point, devises logarithms, and uses numbered 
sticks for calculation. 

William Oughtred invents the circular slide rule based on Napier's 
logarithms. 

J.H.Mueller dreams up his "Difference Engine," but like many dot com 
companies, he cannot get the funds from investors to build it. 

Charles Babbage begins to redesign and build Muellefs Difference Engine 
with funding from the British government. 

Babbage changes his focus from the Difference Engine to a new version 
called the Analytical Engine. 

Ada Eovelace becomes the world's first programmer by putting together 
methods of computing using Babbage's notes on the Analytical Engine. 

The British government pulls funding for the construction of the Difference 
Engine. 

Babbage completes 21 drawings for a new improved second version of the 
Difference Engine but stili does not complete construction. 

The Difference Engine is finally completely built, but by another group not 
including Babbage. 

Herman Hollerith, whose electric tabulating system was used for the 1890 
census, establishes the Tabulating Machine Company. TMC will later 
become IBM. 

Atanasoff and Berry build the first electronic (and non-programmable) 
computer named ABC. Zuse completes the Z3 machine, the world's first fully 
functional program in an automatically controlled electro-mechanical 
computer. It has a 64-word memory and computes at three seconds per 
multiplication. 

Howard Aiken completes the first programmable computer, the Mark I, using 
punched paper tape for programming and vacuum tubes and relays to 
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Table A.I. A Brief History of Programming 


Year 


1945 

1951 

1957 

1958 

1958 

1959 

1960 
1962 

1964 

1965 

1967 

1968 

1968 

1969 

1971 

1972 


Event 

calculate problems. 

Zuse develops "Plankalkul" (short for plain calculus), which is considered the 
first programming language and was designed to be a chess-playing (i.e. 
game) program. Also, on Sept 9th, working on a prototype of the Mark II, 
Grace Murray finds the first computer "bug," an actual moth that eaused a 
relay failure. 

Betty Holberton ereates a "Sort Merge Generator," a predeeessor to modern 
compilers. 

FORTRAN appears, short for Mathematical FORmula TRANslating System. 
Heading the FORTRAN team is John Backus, who also goes on to eontribute 
to the development of ALGOL and BNF. 

John McCarthy introduces the Lisp programming language. 

First eomputers to be built with transistors instead of vacuum tubes. 

There are now over 200 programming languages in existence. 

COBOL, ereated by the Conferenee on Data Systems and Languages, is 
launched for business applieations. 

Spacewar, arguably the first video game ever, is invented at MIT by a 
graduate student named Steve Russei. 

At Dartmouth University, professors John G.Kemeny and Thomas E. Kurtz 
invent BASIC. The first BASIC program runs on May 1, 1964 (at around 4 
a.m.). 

Ken Iverson develops the APL language at IBM. 

IBM announees that it will no longer bundle Software and hardware together, 
but rather will sell them separately. This business move is considered the 
beginning of the Software industry. 

Edsgar Dijkstra first writes about the harmful effeets of the goto statement. 
Intel is formed and incorporated on July 18th. 

AETRAN, a EORTRAN variant, appears. COBOE is offieially defined by 
ANSI. 

Kenneth Thomson and Dennis Ritchie formulate UNIX at AT&T Bell Eabs. 
Donald Knuth writes Volume 1 of the Art of Computer Programming, 
eonsidered the first eomputer programming book. 

Niklaus Wirth develops Paseal, a predeeessor of Modula-2. 

Nolan Buchnelfs game Pong is so popular that he founds Atari.Rary 
Tamlinson ereates e-mail to send personal messages aeross Arpnet (Arpnet 
will beeome the Internet;currently it is used only by the military). Smalltalk 
is developed by Xerox PARCs learning research group. Denis Ritehie 
develops C at Bell Labs. 
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Year 


1975 


1976 

1977 

1979 

1980 

1981 

1983 

1984 

1985 

1986 

1987 

1989 

1990 

1991 

1992 

1993 

1994 

1995 

1996 


Table A.I. A Brief History of Programming 

Event 

The Altair 8800 is available in January as a kit you can order and build from 
Popular Mechanics, and the PC is born.Bill Gates and Paul Allen write a 
version of BASIC that they sell to MIPS (Micro Instrumentation and 
Telemetry Systems) on a per-copy royalty basis.Scheme, a Lisp dialect by 
G.L.Steele and G.J.Sussman, appears. 

Crowther and Woods create the first adventure game called—^you guessed 
it—Adventure. Steve Jobs and Steve Wozniak design and build the Apple I. 

Bili Gates and Paul Allen found Microsoft in Albuquerque, New Mexico. 

Pac Man appears. 

IBM selects PC-DOS from the Microsoft Corporation as the operating 
System for its new PC. Smalltalk-80 appears.Bjarne Stroustrup develops a set 
of languages, collectively referred to as "C With Classes," which serves as 
the breeding ground for C++. 

Japan begins the Fifth Generation Computer System project using Prolog as 
the primary language. 

Microsoft announces "Windows," a graphical user interface for PCs. 
Windows doesn't actually ship, however, until 1985. The first C compilers 
for microcomputers are released. In July the first implementation of C++ 
appears. 

The Macintosh is unveiled, with much glitter and hype, at the Super 
Bowl.William Gibson coins the term "cyberspace" in his novel Neuromancer. 

Windows finally launches. The C++ language is issued from Bell Labs. The 
Intel 80386 chip with 32-bit processing is released. 

The programming language Eiffel appears. 

The Perl programming language is released. 

The C programming language is standardized by ANSI. 

By now more than 54 million computers are in use in the United States alone, 
and the first commercially available dial-up Internet access appears. 

The Python programming language is released. 

The programming language Dylan is released by Apple. 

The Ruby programming language is released. 

The Lua programming language is released.Netscape's first browser becomes 
available. 

Sun Microsystems releases Java. 

One out of every three homes in the United States has a computer. 
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Appendix B. Meet the Family 


After the first high-level languages were developed in the 1950s, dozens of other 
languages popped up and followed suit. Today, you ean't surf the Web or sit on a busy 
subway without eneountering them in use in some form or another. This book foeuses 
on three languages most eommonly used in game shops, but there are dozens of others 
in popular use. 
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ABC 


Created by Leo Geurts, Lambert Meertens, and Steven Pemberton. The idea behind 
ABC was to ereate a simple, interactive language designed for quiek and easy 
programming. ABC was originally intended to replaee BASIC. 
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Ada 


Ada was developed in the 1970s by the United States Department of Defense. Named 
after Lady Ada Lovelaee Byron, Ada is a general-purpose language used for everything 
from business apps to roeket seienee. Ada is mandatory for the development of many 
major U.S. military projects and has been used for large real-time Systems for air-traffic 
eontrol and banking. 
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AFNOR 


AFNOR isn't actually a language, but a standards-setting organization. AFNOR is an 
acronym for Association Fran 9 ais Normal and is part of the International Organization 
for Standardization that also includes ANSI (American National Standards Institute), 
the BSI (British Standards Institution), DIN (Deutsche Institut fur Normung), and other 
standards organizations. 
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c 


C is credited to Dennis Ritchie at Bell Labs in 1972. C was originally a Systems 
language for LTNIX on the PDP-11 and was briefly named NB. Partly due to its free 
distribution with LTNIX, C beeame the language most widely used for Software 
implementation. C has gone through a few inearnations, including K&R (Kemighan and 
Ritehie) C, and ANSI C, and has been lately revamped as the objeet-oriented C++. 
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C++ 


Both C and C++ are considered high-level languages, although they are mueh eloser to 
maehine assembly than other high-level languages. This makes them very effieient but 
sometimes diffieult to implement. C++ was developed at Bell Labs by Bjarne Strousrup, 
who took C and added objeet-oriented programming (OOP) features. The C family is 
espeeially brilliant when it eomes to ereating the very popular graphies and Windows- 
based applieations and has a wonderful seetion of well-designed libraries. 
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Cobol 


Cobol is short for Common Business Oriented Languages. Cobol goes way back to the 
1950s and is considered one of the old timers (with FORTRAN being its father). 

Cobofs foeus was, of eourse, business applieations that ran on large eomputers. Baek in 
the 195 Os Cobol wasn't really eonsidered high-level, it was eonsidered wordy. The 
wordiness makes it easy to follow the business jargon, but it also requires a lot more 
typing than other languages. 
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Eiffel 


Released by Bertrand Meyer in 1986. Eiffel is considered an object-oriented language, 
has automatic garbage collection, and possesses interfaces to routines written in other 
languages. It is implemented as a C preprocessor. 
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FORTRAN 


FOTRAN is an acronym for FORmula TRANslator. It is probably the oldest high-level 
language, originally designed at IBM by John Backus in the late 1950s. The language 
has branched into several different versions, many of whieh are stili in use today. 
FORTRAN's niche is mathematical eomputations, and it is most commonly used in 
universities. 
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GNU Octave 


Used for numerical computations, GNU Octave has lots of tools for common math and 
algebra functions and tasks. GNU Octave is customizable, can run via command line or 
through batch, and can dynamically load up FORTRAN or C for other tasks. GNU 
Octave is distributed under the GNU General Public License published by the Free 
Software Foundation. 
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Java 


Originally developed by Sun Microsystems for set-top boxes and handheld devices in 
an incarnation known as Oak, Java moved to the World Wide Web in 1995 and took off 
beeause it was multi-platform. Java is similar to C++ but was designed with OOP and 
seeurity in mind from the ground up, and efforts were made in its structure to remove 
features that eaused eommon errors and bugs (like pointers and garbage eolleetion). 
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Icon 


Icon is another high-level language used often in research and text processing. Icon was 
developed at the University of Arizona and is loosely based on Bell Lab's Snobol. 
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Modula 


Short for MODUlar LAnguage, Modula precedes Modula-2, developed as a system 
language for the Lilith workstation. The Central concept behind Modula is the module— 
a programming construet that can be used to encapsulate a set of related subprograms 
and data structures. Modules are also restricted in their visibility firom other portions of 
the program. Modula-2 precedes Modula-2-i- and Modula-3. 
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Pascal 


Pascal was developed in the late 1960s by Niklaus Wirth and was named after Blaise 
Pascal, who was a 17th-century French mathematician who constructed early adding 
machines. In addition to being high-level, Pascal is also a structured programming 
language, which forces design into its very nature. Pascal is often used as a teaching 
tool because of its regimented structure. 
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Perl 


Short for Practical Extraction and Report Language, Perl was released in 1987 by Larry 
Wall, who developed the language while working for the National Seeurity Ageney. 
Larry wanted his language to be based on eommon sense programming teehniques and 
wanted applieations developed with Perl to be quiekly and easily written. Perl was built 
originally as a simple language to sean text files, extraet Information from those files, 
and print reports based on that Information. It has blossomed into a full programming 
language with hundreds of supplemental libraries. Perl is easy to learn and is eommonly 
found on the Internet, used in eonjunetion with CGI and HTML. 
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PHP 


PHP is a domain-specific language for Web server-side scripting. PHP embeds itself 
into HTML to create dynamic Web pages. The language has a syntax similar to Perfs or 
C's and is comparable to CGI; its primary strength is in database access. PHP was 
originally developed in 1994 but has gone through at least one major rewrite and has 
had many contributors. 
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Prolog 


Short for PROgramming LOGic, Prolog is a high-level language based on the discipline 
of traditional logic. While most computer languages perform a sequence of commands, 
Prolog has an entirely different approach. Prolog first creates definitions and 
assumptions and then uses them to solve logic problems. For Prolog, a program is just a 
list of facts and rules. Prolog is most often found in AI experiments and expert Systems 
(programs that function like human experts). 
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PureBasic 


A high-level language based on BASIC, a revival of sorts that focuses on keeping 
programming linear and simple. PureBasic is a good learning tool with a few games 
under its belt, including Bricklinerby Wegroup, Krakout 2 Unlimited(a remake of the 
Commodore 64 game Krakout), and a few tities by Reelmedia. 
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Smalltalk 


Smalltalk was created by Software Concepts Group (i.e.Xerox) in a development led by 
Alan Kay in the early 1970s. Smalltalk took the concepts of class and message from 
Simula-67 and made them pervasive, basically creating the quintessential object- 
oriented language. Early versions were Smalltalk-72, Smalltalk-74, and Smalltalk-76; 
now we're on Smalltalk-80. 
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Squeak 

Disney and Paul Allen's Interval Research Lab helped develop the open source Squeak 
language. Squeak has three environments: one for young children, one for middle 
school through adult age, and one for experts who are into "deep computing." 
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